{"id":14967363,"url":"https://github.com/davellanedam/node-express-mongodb-jwt-rest-api-skeleton","last_synced_at":"2025-05-15T15:08:18.024Z","repository":{"id":32974540,"uuid":"148357200","full_name":"davellanedam/node-express-mongodb-jwt-rest-api-skeleton","owner":"davellanedam","description":"This is a basic API REST skeleton written on JavaScript using async/await. Great for building a starter web API for your front-end (Android, iOS, Vue, react, angular, or anything that can consume an API). Demo of frontend in VueJS here: https://github.com/davellanedam/vue-skeleton-mvp","archived":false,"fork":false,"pushed_at":"2023-07-22T11:35:23.000Z","size":1984,"stargazers_count":904,"open_issues_count":12,"forks_count":286,"subscribers_count":45,"default_branch":"development","last_synced_at":"2025-04-25T21:02:14.915Z","etag":null,"topics":["api","async-await","chai","eslint","express","front-end","javascript","jwt","jwt-authentication","mocha","mongodb","mongoose","mvp","node","nodejs","postman","redis","rest","testing","token"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"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/davellanedam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-09-11T17:53:07.000Z","updated_at":"2025-04-22T14:01:38.000Z","dependencies_parsed_at":"2024-06-18T21:33:58.889Z","dependency_job_id":"35925e8e-a941-4747-9d3a-701703771f0e","html_url":"https://github.com/davellanedam/node-express-mongodb-jwt-rest-api-skeleton","commit_stats":{"total_commits":322,"total_committers":8,"mean_commits":40.25,"dds":0.0496894409937888,"last_synced_commit":"50b15eb84fb6d94a6a6f6940b43e9e614770fa53"},"previous_names":[],"tags_count":126,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davellanedam%2Fnode-express-mongodb-jwt-rest-api-skeleton","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davellanedam%2Fnode-express-mongodb-jwt-rest-api-skeleton/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davellanedam%2Fnode-express-mongodb-jwt-rest-api-skeleton/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davellanedam%2Fnode-express-mongodb-jwt-rest-api-skeleton/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davellanedam","download_url":"https://codeload.github.com/davellanedam/node-express-mongodb-jwt-rest-api-skeleton/tar.gz/refs/heads/development","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254364270,"owners_count":22058878,"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":["api","async-await","chai","eslint","express","front-end","javascript","jwt","jwt-authentication","mocha","mongodb","mongoose","mvp","node","nodejs","postman","redis","rest","testing","token"],"created_at":"2024-09-24T13:37:55.483Z","updated_at":"2025-05-15T15:08:13.006Z","avatar_url":"https://github.com/davellanedam.png","language":"JavaScript","readme":"# Node.js express.js MongoDB JWT REST API - Basic Project Skeleton\n\n[![Author](http://img.shields.io/badge/author-@davellanedam-blue.svg?style=flat-square)](https://twitter.com/davellanedam)\n[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](https://github.com/davellanedam/node-express-mongodb-jwt-rest-api-skeleton/blob/master/LICENSE)\n[![Tag](https://img.shields.io/github/tag/davellanedam/node-express-mongodb-jwt-rest-api-skeleton.svg?style=flat-square)](https://github.com/davellanedam/node-express-mongodb-jwt-rest-api-skeleton/tags)\n[![Travis](https://img.shields.io/travis/com/davellanedam/node-express-mongodb-jwt-rest-api-skeleton.svg?style=flat-square)]()\n[![npm downloads](https://img.shields.io/npm/dt/node-express-mongodb-jwt-rest-api-skeleton.svg?style=flat-square\\\u0026label=npm%20downloads)]()\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/fb6f20533c0f41b6b00da95ba634cd5e)](https://www.codacy.com/app/davellanedam/node-express-mongodb-jwt-rest-api-skeleton?utm_source=github.com\\\u0026utm_medium=referral\\\u0026utm_content=davellanedam/node-express-mongodb-jwt-rest-api-skeleton\\\u0026utm_campaign=Badge_Grade)\n\n## Getting started\n\nThis is a basic API REST skeleton written on JavaScript using async/await. Great for building a starter web API for your front-end (Android, iOS, Vue, react, angular, or anything that can consume an API)\n\nThis project is created to help other developers create a **basic REST API in an easy way with Node.js**. This basic example shows how powerful and simple JavaScript can be. Do you want to contribute? Pull requests are always welcome to show more features.\n\n## Buy me a coffee\n\nHi! I'm Daniel Avellaneda, I'm an open source enthusiast and devote my free time to building projects in this field.\n\nI'm the creator and maintainer of [node-express-mongodb-jwt-rest-api-skeleton](https://github.com/davellanedam/node-express-mongodb-jwt-rest-api-skeleton/blob/master/README.md) and [vue-skeleton-mvp](https://github.com/davellanedam/vue-skeleton-mvp/blob/master/README.md)\n\nThese projects are a \"starter web app kit\" for any developer who wants to build their own app without starting from scratch: API + Frontend\n\nBoth projects have been downloaded thousands of times by web developers around the world.\n\nI'm doing my best to provide you a good experience when using my apps, so if you like what I'm doing and wish to say \"thanks!\", please buy me a coffee :coffee:\n\n\u003ca href=\"https://www.buymeacoffee.com/muGHf41NT\" target=\"_blank\"\u003e\u003cimg src=\"https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png\" alt=\"Buy Me A Coffee\" style=\"height: auto !important;width: auto !important;\" \u003e\u003c/a\u003e\n\nFeel free to send me a tweet \u003chttps://twitter.com/davellanedam\u003e, share this with others or make a pull request\n\n## Features\n\n*   Multiple environment ready (development, production)\n*   Custom email/password user system with basic security and blocking for preventing brute force attacks.\n*   Compressed responses.\n*   Secured HTTP headers.\n*   CORS ready.\n*   Cache ready (Redis).\n*   HTTP request logger in development mode.\n*   i18n ready (for sending emails in multiple languages).\n*   User roles.\n*   Pagination ready.\n*   User profile.\n*   Users list for admin area.\n*   Cities model and controller example.\n*   Login access log with IP, browser and country location (for country it looks for the header `cf-ipcountry` that CloudFlare creates when protecting your website).\n*   API autogenerated documentation by Postman.\n*   API collection example for Postman.\n*   Testing with mocha/chai for API endpoints.\n*   NPM scripts for cleaning and seeding the MongoDB database.\n*   NPM script for keeping good source code formatting using prettier and ESLint.\n*   Use of ESLint for good coding practices.\n*   Mailer example with Nodemailer and Mailgun.\n*   Ability to refresh token\n*   JWT Tokens, make requests with a token after login with `Authorization` header with value `Bearer yourToken` where `yourToken` is the **signed and encrypted token** given in the response from the login process.\n\n## Requirements\n\n*   Node.js **10+**\n*   MongoDB **3.6+**\n*   Redis **5.0+**\n\n## Demo\n\nA demo of this API is located at: \u003chttps://api-demo.daniel-avellaneda.com\u003e\n\n### Login credentials\n\nemail: `admin@admin.com`\\\npassword: `12345`\n\n**IMPORTANT:** Database resets every 30 mins like \"12:00am, 12:30am, 1:00am\" and so on. So anything you do with the API will be lost after a short time.\n\n[API documentation](###api-documentation)\\\n[Postman API example collection](###postman-api-example-collection)\\\nIf you want to test it don´t forget to change the server variable to:\\\n`https://api-demo.daniel-avellaneda.com`\n\nDemo is also linked to a VueJS project that shows how this API can be integrated to a frontend that is able to consume an API.\\\nRepo is here: \u003chttps://github.com/davellanedam/vue-skeleton-mvp\u003e\\\nRunning demo is here: \u003chttps://vue-demo.daniel-avellaneda.com\u003e\n\n## How to install\n\n### Using Git (recommended)\n\n1.  Clone the project from github. Change \"myproject\" to your project name.\n\n```bash\ngit clone https://github.com/davellanedam/node-express-mongodb-jwt-rest-api-skeleton.git ./myproject\n```\n\n### Using manual download ZIP\n\n1.  Download repository\n2.  Uncompress to your desired directory\n\n### Install npm dependencies after installing (Git or manual download)\n\n```bash\ncd myproject\nnpm install\nnpm update\n```\n\n### Setting up environments (development or production)\n\n1.  In the root this repository you will find a file named `.env.example`\n2.  Create a new file by copying and pasting the file and then renaming it to just `.env`\n3.  The file `.env` is already ignored, so you never commit your credentials.\n4.  Change the values of the file to your environment (development or production)\n5.  Upload the `.env` to your environment server(development or production)\n6.  If you use the postman collection to try the endpoints, change value of the variable `server` on your environment to the url of your server, for development mode use \u003chttp://localhost:3000\u003e\n\n**IMPORTANT:** By default token expires in 3 days (4320 minutes set in .env.example). You can refresh token at endpoint GET /token. If everything it´s ok you will get a new token.\n\n### Mailer\n\nTo ensure the deliverability of emails sent by this API, `Mailgun` is used for mailing users when they sign up, so if you want to use that feature go sign up at their website \u003chttps://www.mailgun.com\u003e\n\nIf you want to try a different method it´s ok, I used \u003chttps://nodemailer.com\u003e for this API and they have different transport methods like: smtp.\n\n### i18n\n\nLanguage is automatically detected from `Accept-Language` header on the request. So either you send locale manually on the request or your browser will send its default, if `Accept-Language` header is not sent then it will use `en` locale as default.\n\n## How to run\n\n### Database cleaning and seeding samples\n\nThere are 3 available commands for this: `fresh`, `clean` and `seed`.\n\n```bash\nnpm run command\n```\n\n*   `fresh` cleans and then seeds the database with dynamic data.\n*   `clean` cleans the database.\n*   `seed` seeds the database with dynamic data.\n\n### Running in development mode (lifting API server)\n\n```bash\nnpm run dev\n```\n\nYou will know server is running by checking the output of the command `npm run dev`\n\n```bash\n****************************\n*    Starting Server\n*    Port: 3000\n*    NODE_ENV: development\n*    Database: MongoDB\n*    DB Connection: OK\n****************************\n```\n\n### Running tests\n\nIt´s a good practice to do tests at your code, so a sample of how to do that in `mocha/chai` is also included in the `/test` directory\n\n```bash\nnpm run test\n```\n\n### Formatting code\n\nFormat your code with prettier by typing:\n\n```bash\nnpm run format\n```\n\n### Formatting markdown files\n\nFormat all your markdown files with remark by typing:\n\n```bash\nnpm run remark\n```\n\n### Linting code\n\nLint your code with ESLint by typing:\n\n```bash\nnpm run lint\n```\n\n## Usage\n\nOnce everything is set up to test API routes either use Postman or any other api testing application. Default username/password combination for login is `admin@admin.com/12345`.\n\n### API documentation\n\n\u003chttps://documenter.getpostman.com/view/487539/RWaHwoLV\u003e\n\n### Postman API example collection\n\nYou can import the example collection to Postman. To import, click the import button located and select `postman-example.json` located within the root directory.\n\nGo to `manage environments` to create environments for development, production, etc. On each of the environments you create you will need to:\n\n1.  Create a new key `authToken` and within the `/login` request this value is automatically updated after a successfull login through a script located in the `tests` tab. Each time you make a request to the API it will send `Authorization` header with the `token` value in the request, you can check this on the headers of users or cities endpoints in the Postman example.\n\n2.  Create a second key `server` with the url of your server, for development mode use \u003chttp://localhost:3000\u003e\n\nThis is a REST API, so it works using the following HTTP methods:\n\n*   GET (Read): Gets a list of items, or a single item\n*   POST (Create): Creates an item\n*   PATCH (Update): Updates an item\n*   DELETE: Deletes an item\n\n### Creating new models\n\nIf you need to add more models to the project just create a new file in `/app/models/` and it will be loaded dynamically.\n\n### Creating new routes\n\nIf you need to add more routes to the project just create a new file in `/app/routes/` and it will be loaded dynamically.\n\n### Creating new controllers\n\nWhen you create a new controller, try to also create another folder with validations and helpers. Ex. `/countries`, `/countries/validators` and `/countries/helpers`. An example of this is included in the repository.\n\n## Bugs or improvements\n\nFeel free to report any bugs or improvements. Pull requests are always welcome.\n\n## License\n\nThis project is open-sourced software licensed under the MIT License. See the LICENSE file for more information.\n","funding_links":["https://www.buymeacoffee.com/muGHf41NT"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavellanedam%2Fnode-express-mongodb-jwt-rest-api-skeleton","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavellanedam%2Fnode-express-mongodb-jwt-rest-api-skeleton","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavellanedam%2Fnode-express-mongodb-jwt-rest-api-skeleton/lists"}