{"id":26139831,"url":"https://github.com/leanstacks/sample-api-node-express-mongo","last_synced_at":"2026-04-06T01:34:32.290Z","repository":{"id":37012042,"uuid":"483611520","full_name":"leanstacks/sample-api-node-express-mongo","owner":"leanstacks","description":"Example REST API using Node, Express, and MongoDB","archived":false,"fork":false,"pushed_at":"2022-08-31T10:42:52.000Z","size":458,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-17T01:04:29.402Z","etag":null,"topics":["docker","expressjs","mongoosejs","nodejs","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leanstacks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-04-20T10:38:10.000Z","updated_at":"2024-04-17T01:04:29.403Z","dependencies_parsed_at":"2023-01-16T15:01:33.467Z","dependency_job_id":null,"html_url":"https://github.com/leanstacks/sample-api-node-express-mongo","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leanstacks%2Fsample-api-node-express-mongo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leanstacks%2Fsample-api-node-express-mongo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leanstacks%2Fsample-api-node-express-mongo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leanstacks%2Fsample-api-node-express-mongo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leanstacks","download_url":"https://codeload.github.com/leanstacks/sample-api-node-express-mongo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242960672,"owners_count":20213193,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","expressjs","mongoosejs","nodejs","typescript"],"created_at":"2025-03-11T02:37:23.517Z","updated_at":"2025-12-30T19:58:55.231Z","avatar_url":"https://github.com/leanstacks.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sample: REST API using Node.js, Express, and MongoDB\n\nAn example REST API using Node, Express, and MongoDB\n\n## Install\n\n### Project Pre-requisites\n\nThe project has the following pre-requisites which must be in place prior to installation of the project libraries.\n\n1. [Node Version Manager](https://github.com/nvm-sh/nvm)\n\n### Install the Dependencies\n\nTo install the project dependencies, issue the following commands at a terminal prompt.\n\n```\nnvm use\n\nnpm install\n```\n\n## Run\n\n### Local Development\n\nTo run the project on your local machine, issue the following commands at a terminal prompt.\n\n```bash\n# start the application\nnpm start\n\n# or to start forcing in-memory database\nMONGO_INMEMORY=true npm start\n```\n\nNode Package Manager (NPM) runs the `start` script. This script starts the Express server and listens for requests on port `3001`.\n\n\u003e **NOTE:** The `start` script uses `nodemon` to watch the `/src` directory for changes to source files and restarts the application when source file changes are saved.\n\n## Test\n\nThis project provides a REST API. You may test this API using an API client such as PostMan or by issuing `curl` commands at a terminal prompt.\n\nThe following sections provide examples of `curl` commands.\n\n### Get all Todos\n\nTo fetch all todos, issue the following `curl` command at a terminal prompt.\n\n```\ncurl [--verbose] http://localhost:3001/v1/todos\n```\n\n\u003e **NOTE:** You may optionally include the `--verbose` option to view the complete details the call.\n\n### Get a single Todo by Identifier\n\nTo fetch a single todo by its identifier, issue the following `curl` command at a terminal prompt.\n\n```\ncurl [--verbose] http://localhost:3001/v1/todos/:id\n```\n\nReplace the `:id` portion of the URL with the `id` attribute of the todo you wish to fetch.\n\n### Create a Todo\n\nTo create a todo, issue the following `curl` command at a terminal prompt.\n\n```\ncurl --request POST \\\n     --header 'Content-Type: application/json' \\\n     --data '{\"title\": \"Buy groceries\", \"isComplete\": false}' \\\n     --verbose \\\n     http://localhost:3001/v1/todos\n```\n\n### Update a Todo\n\nTo update one or more attributes of a todo, issue the following `curl` command at a terminal prompt.\n\n```\ncurl --request PUT \\\n     --header 'Content-Type: application/json' \\\n     --data '{\"isComplete\": true}' \\\n     --verbose \\\n     http://localhost:3001/v1/todos/:id\n```\n\nReplace the `:id` portion of the URL with the `id` attribute of the todo you wish to update.\n\n### Delete a Todo\n\nTo delete a todo, issue the following `curl` command at a terminal prompt.\n\n```\ncurl --request DELETE \\\n     --verbose \\\n     http://localhost:3001/v1/todos/:id\n```\n\nReplace the `:id` portion of the URL with the `id` attribute of the todo you wish todelete.\n\n### Server Health\n\nTo assess if the server is processing requests, use the health check endpoint at path: `/health`.\n\nTo test this endpoint, issue the following `curl` command at a terminal prompt.\n\n```\ncurl [--verbose] http://localhost:3001/health\n```\n\n| Status Code | Description                 |\n| ----------- | --------------------------- |\n| 200         | Service is healthy.         |\n| 4xx or 5xx  | Service is **not** healthy. |\n\nIf running the server in a load balanced cluster, this endpoint should be used to determine the node's availability.\n\n### Server Status\n\nTo perform a deeper assessment of the server status including downstream dependencies, use the status endpoint at path: `/status`.\n\nTo perform a status check, issue the following `curl` command at a terminal prompt.\n\n```\ncurl [--verbose] http://localhost:3001/status\n```\n\n\u003e **NOTE:** Do **not** use the status check to assess if the server is up, i.e. from a load balancer. The status check consumes more server resources than the health check.\n\n## Docker\n\n\u003e **NOTE:** To use Docker with this project you must have [Docker installed](https://docs.docker.com/get-docker/) on the machine where Docker commands will be executed, e.g. your local machine and/or a CI/CD pipeline.\n\nThis application may be packaged and run as a Docker container. Or you may run the application **and** MongoDB with Docker Compose, see the section further below.\n\n### Building the Docker Image\n\nTo build the Docker image, issue the following commands at a terminal prompt.\n\n```bash\n# build the application\nnpm run build\n\n# build the docker image\nnpm run docker:build\n```\n\nThis command builds a Docker container image named `leanstacks/todo-api` with the tag `latest`.\n\n### Running the Docker Container\n\nTo run the application with Docker, first build the Docker image following the instructions in the section above.\n\nAfter creating the Docker image, issue the following command at a terminal prompt to start a new running container using that image.\n\n```bash\n# via npm scripts\nnpm run docker:run\n\n# with docker\ndocker container run --publish 3001:3001 leanstacks/todo-api\n```\n\nThe command above starts a new Docker container in the foreground (i.e. it is **not** detached). This is fine for local development when you may wish to have the application logs printed to the console; however, it should not be used in production.\n\nTo run the container in the background (i.e. detached), issue the following command at a terminal prompt.\n\n```bash\n# via npm scripts\nnpm run docker:run:detached\n\n# with docker\ndocker container run --publish 3001:3001 --detached leanstacks/todo-api\n```\n\n### Manage Docker Containers\n\nTo list running Docker containers on the machine, issue the following command at a terminal prompt.\n\n```\ndocker container ls\n```\n\nTo view **ALL** containers regardless of their status, issue the following command at a terminal prompt.\n\n```\ndocker container ls --all\n```\n\n\u003e **NOTE:** The container list provides the container name such as `sleepy_willow`, etc. The container name is used in some container management commands illustrated below.\n\nTo stop a running container, issue the following command at a terminal prompt.\n\n```\ndocker container stop [CONTAINER]\n```\n\nTo start a stopped container, issue the following command at a terminal prompt.\n\n```\ndocker container start [CONTAINER]\n```\n\nTo remove a stopped container, issue the following command at a terminal prompt.\n\n```\ndocker container rm [CONTAINER]\n```\n\nTo remove **ALL** stopped containers, issue the following command at a terminal prompt.\n\n```\ndocker container prune\n```\n\n## Docker Compose\n\nThis project is Docker Compose ready. Use Docker Compose to run the project **and** MongoDB on your local machine without needing to install the database.\n\n\u003e **NOTE:** Requires that you have Docker and Docker Compose installed.\n\n### Start the Application\n\nTo start the application, issue the following command at a terminal prompt.\n\n```bash\n# if building a new image with --build, first build the application\nnpm run build\n\n# start the environment\ndocker compose up [--build] --detach\n```\n\nInclude the `--build` option and Docker will rebuild the application Docker image using the latest code, using that image when running the application.\n\n### Stop the Application\n\nTo stop the application, issue the following command at a terminal prompt.\n\n```\ndocker compose down\n```\n\nThis command stops and removes the containers and cleans up ephemeral resources.\n\n### View Logs\n\nTo view the logs from running compose application, issue the following command at a terminal prompt.\n\n```\ndocker compose logs --follow\n```\n\nPress `ctrl-C` to return to the command prompt.\n\n## Configuration Guide\n\nThis section provides detailed information regarding the configuration of this component.\n\n### Variable Expansion\n\nVariable expansion is supported. This means that the value of a configuration variable may include a reference to a previously defined variable. For example...\n\n```\nFOO=foo             // foo\nBAR=bar             // bar\nFOOBAR=${FOO}${BAR} // foobar\n```\n\n## Configuration Values\n\n| name                          | default                                  | description                                                                              |\n| ----------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------- |\n| AUTH_ATTEMPTS_MAX             | `3`                                      | The maximum number of invalid authentication attempts after which the account is locked. |\n| AUTH_PASSWORD_EXPIRES_IN_DAYS | `90`                                     | The number of days after which a password is flagged as expired.                         |\n| AUTH_PASSWORD_HISTORY_COUNT   | `5`                                      | The maximum number of password history records to store.                                 |\n| AUTH_PASSWORD_REUSE_COUNT     | `3`                                      | The number of password history records to examine for password reuse.                    |\n| JWT_AUDIENCE                  |                                          | The JWT audience attribute value.                                                        |\n| JWT_ACCESS_TOKEN_EXPIRES_IN   | `3600`                                   | The JWT duration an access token is valid.                                               |\n| JWT_ISSUER                    |                                          | The JWT issuer attribute value.                                                          |\n| JWT_REFRESH_TOKEN_EXPIRES_IN  | `86400`                                  | The JWT duration a refresh token is valid.                                               |\n| JWT_SECRET                    |                                          | The JWT signing secret value.                                                            |\n| LOG_LEVEL                     | `info`                                   | The logging level threshold.                                                             |\n| MONGO_DBNAME                  | `todo_db`                                | The MongoDB database name.                                                               |\n| MONGO_INMEMORY                | `false`                                  | Use an in-memory MongoDB instance.                                                       |\n| MONGO_URL                     | `mongodb://username:password@host:27017` | The connection URL for MongoDB. Optional if `MONGO_INMEMORY` is true.                    |\n| NODE_ENV                      | `development`                            | The environment type. One of: `development`, `test`, `production`                        |\n| SERVER_PORT                   | `3001`                                   | The port on which the application listens for requests.                                  |\n| SERVER_HOST                   | `localhost`                              | The hostname (or DNS name) on which the server is hosted.                                |\n| SERVER_BASEURL                | `http://${SERVER_PORT}:${SERVER_PORT}`   | The base URL of the application.                                                         |\n\n## Related Information\n\n[Docker Install Guide](https://docs.docker.com/get-docker/)  \n[Docker CLI Reference](https://docs.docker.com/engine/reference/commandline/docker/)  \n[Docker Compose][dockercompose]\n\n[dockercompose]: https://docs.docker.com/compose/ 'Docker Compose'\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleanstacks%2Fsample-api-node-express-mongo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleanstacks%2Fsample-api-node-express-mongo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleanstacks%2Fsample-api-node-express-mongo/lists"}