RESTful API generator using NodeJS, Express and MongoDB. Watch https://youtu.be/6x-ijyG-ack
npm install generator-restš¹ Watch this video for an overview on how to use generator-rest and deploy your project to Heroku.
If you find this useful, please don't forget to star āļø the repo, as this will help to promote the project.
Follow me on Twitter and GitHub to keep updated about this project and others.
- Highly customizable - You can choose what to install
- Really RESTful - It follows the best practices
- ES6! - Using babel
- User registration API - Using passport (optional)
- Social login API - Facebook, Google and GitHub (optional)
- Password reset API - Sending emails with SendGrid API (optional)
- Listing query strings - q, page, limit, fields etc. already provided by querymen
- Query string validator - Using querymen
- Request body validator - Using bodymen
- Standard error responses - Using querymen and bodymen error handlers
- Unit and integration tests - Using Jest
- Continuous integration support - Using Travis CI
- API docs generator - Using apidoc
- Love ā„ - Using me
First, install Yeoman and generator-rest using npm (we assume you have pre-installed node.js).
``bash`
npm install -g yo
npm install -g generator-rest
Then, you can use yo to generate your project.
`bash`
yo rest # generate a new project
yo rest:api # generate a new api endpoint inside your project
After you generate your project, these commands are available in package.json.
`bash`
npm test # test using Jest
npm run coverage # test and open the coverage report in the browser
npm run lint # lint using ESLint
npm run dev # run the API in development mode
npm run prod # run the API in production mode
npm run docs # generate API docs
First, you will need to install and run MongoDB in another terminal instance.
`bash`
$ mongod
Then, run the server in development mode.
`bash`
$ npm run dev
Express server listening on http://0.0.0.0:9000, in development mode
If you choose to generate the authentication API, you can start to play with it.
> Note that creating and authenticating users needs a master key (which is defined in the .env file)
Create a user (sign up):
`bash`
curl -X POST http://0.0.0.0:9000/users -i -d "email=test@example.com&password=123456&access_token=MASTER_KEY_HERE"
It will return something like:
`bash`
HTTP/1.1 201 Created
...
{
"id": "57d8160eabfa186c7887a8d3",
"name": "test",
"picture":"https://gravatar.com/avatar/55502f40dc8b7c769880b10874abc9d0?d=identicon",
"email": "test@example.com",
"createdAt": "2016-09-13T15:06:54.633Z"
}
Authenticate the user (sign in):
`bash`
curl -X POST http://0.0.0.0:9000/auth -i -u test@example.com:123456 -d "access_token=MASTER_KEY_HERE"
It will return something like:
`bash`
HTTP/1.1 201 Created
...
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
"user": {
"id": "57d8160eabfa186c7887a8d3",
"name": "test",
"picture": "https://gravatar.com/avatar/55502f40dc8b7c769880b10874abc9d0?d=identicon",
"email": "test@example.com",
"createdAt":"2016-09-13T15:06:54.633Z"
}
}
Now you can use the eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 token (it's usually greater than this) to call user protected APIs. For example, you can create a new article API using yo rest:api and make the POST /articles endpoint only accessible to authenticated users. Then, to create a new article you must pass the access_token parameter.`bash`
curl -X POST http://0.0.0.0:9000/articles -i -d "title=Awesome Article&content=Yeah Baby&access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
It will return something like:
`bash`
HTTP/1.1 201 Created
...
{
"id": "57d819bfabfa186c7887a8d6",
"title": "Awesome Article",
"content": "Yeah Baby",
"createdAt": "2016-09-13T15:22:39.846Z",
"updatedAt":"2016-09-13T15:22:39.846Z"
}
> Some endpoints are only accessible by admin users. To create an admin user, just pass the role=admin along to other data when calling POST /users.
Here is an example on how to deploy to Heroku using Heroku CLI:
`bashstart a new local git repository
git init
The second time you deploy, you just need to:
bash
git add -A
git commit -m "Update code"
git push heroku master
`Directory structure
$3
You can customize the
and api directories.`
src/
āā api/
ā āā user/
ā ā āā controller.js
ā ā āā index.js
ā ā āā index.test.js
ā ā āā model.js
ā ā āā model.test.js
ā āā index.js
āā services/
ā āā express/
ā āā facebook/
ā āā mongoose/
ā āā passport/
ā āā sendgrid/
ā āā your-service/
āā app.js
āā config.js
āā index.js
$3
Here is where the API endpoints are defined. Each API has its own folder.
#### src/api/some-endpoint/model.js
It defines the Mongoose schema and model for the API endpoint. Any changes to the data model should be done here.
#### src/api/some-endpoint/controller.js
This is the API controller file. It defines the main router middlewares which use the API model.
#### src/api/some-endpoint/index.js
This is the entry file of the API. It defines the routes using, along other middlewares (like session, validation etc.), the middlewares defined in the
file.$3
Here you can put
helpers, libraries` and other types of modules which you want to use in your APIs.- Support optional phone authentication
- Support optional email confirmation process
- Support Twitter and other social login methods
- Socket.io support
PRs are welcome.
@QzSG and all contributors
MIT Ā© Diego Haz
[npm-image]: https://badge.fury.io/js/generator-rest.svg
[npm-url]: https://npmjs.org/package/generator-rest
[travis-image]: https://travis-ci.org/diegohaz/rest.svg?branch=master
[travis-url]: https://travis-ci.org/diegohaz/rest
[coveralls-image]: https://coveralls.io/repos/diegohaz/rest/badge.svg
[coveralls-url]: https://coveralls.io/r/diegohaz/rest