kfili/express-api-template

Railsified express server

express-api-template

A template for starting projects with express as an API. Includes authentication and common middlewares.

At the beginning of each cohort, update the versions in package.json by replace all versions with a glob (*) and running npm update --save && npm update --save-dev. You may wish to test these changes by deleting the node_modules directory and running npm install. Fix any conflicts.

This template follows Rails-like conventions for organizing controller and model code, and has a routing layer which is similar to the Rails routing DSL.

Dependencies

Install with npm install.

• express
• mongoose

At the beginning of each cohort, update the versions in package.json by replace all versions with a glob (*) and running npm update --save && npm update --save-dev. You may wish to test these changes by deleting the node_modules directory and running npm install. Fix any conflicts.

Installation

1. Download this template.
2. Unzip and rename the template directory.
3. Empty README.md and fill with your own content.
4. Move into the new project and git init.
5. Replace all instances of 'express-api-template' with your app name. This includes package.json, various debugger configurations, and the MongoDB store.
6. Install dependencies with npm install.
7. Set a SECRET_KEY in the environment.
8. Run the API server with npm start. If you want your code to be reloaded on change, you should npm install -g nodemon and use nodemon instead of npm start.
9. Once everything is working, make an initial commit.

For development and testing, set the SECRET_KEY from the root of your repository using

echo SECRET_KEY=$(/usr/local/opt/openssl/bin/openssl rand -base64 66 | tr -d '\n') >>.env

In order to make requests from your deployed client application, you will need to set CLIENT_ORIGIN in the environment (e.g. heroku config:set CLIENT_ORIGIN=https://<github-username>.github.io).

Structure

Dependencies are stored in package.json.

Do not configure grunt packages directly in the Gruntfile.js. Instead, store configurations in the grunt directory. You won't need a top-level key, since that's generated by the Gruntfile.js based on the filename of the configuration object stored in the grunt directory.

Developers should store JavaScript files in app/controllers and app/models. Routes are stored in config/routes.js

Tasks

Developers should run these often!

• grunt nag or just grunt: runs code quality analysis tools on your code and complains
• grunt reformat: reformats all your code in a standard style
• grunt test: runs any automated tests

API

Use this as the basis for your own API documentation. Add a new third-level heading for your custom entities, and follow the pattern provided for the built-in user authentication documentation.

Scripts are included in scripts to test built-in actions. Add your own scripts to test your custom API.

Authentication

Verb	URI Pattern	Controller#Action
POST	/sign-up	users#signup
POST	/sign-in	users#signin
PATCH	/change-password/:id	users#changepw
DELETE	/sign-out/:id	users#signout

POST /sign-up

Request:

curl --include --request POST http://localhost:4741/sign-up \
  --header "Content-Type: application/json" \
  --data '{
    "credentials": {
      "email": "an@example.email",
      "password": "an example password",
      "password_confirmation": "an example password"
    }
  }'

scripts/sign-up.sh

Response:

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "user": {
    "id": 1,
    "email": "an@example.email"
  }
}

POST /sign-in

Request:

curl --include --request POST http://localhost:4741/sign-in \
  --header "Content-Type: application/json" \
  --data '{
    "credentials": {
      "email": "an@example.email",
      "password": "an example password"
    }
  }'

scripts/sign-in.sh

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "user": {
    "id": 1,
    "email": "an@example.email",
    "token": "33ad6372f795694b333ec5f329ebeaaa"
  }
}

PATCH /change-password/:id

Request:

curl --include --request PATCH http://localhost:4741/change-password/$ID \
  --header "Authorization: Token token=$TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "passwords": {
      "old": "an example password",
      "new": "super sekrit"
    }
  }'

ID=1 TOKEN=33ad6372f795694b333ec5f329ebeaaa scripts/change-password.sh

Response:

HTTP/1.1 204 No Content

DELETE /sign-out/:id

Request:

curl --include --request DELETE http://localhost:4741/sign-out/$ID \
  --header "Authorization: Token token=$TOKEN"

ID=1 TOKEN=33ad6372f795694b333ec5f329ebeaaa scripts/sign-out.sh

Response:

HTTP/1.1 204 No Content

Users

Verb	URI Pattern	Controller#Action
GET	/users	users#index
GET	/users/1	users#show

GET /users

Request:

curl --include --request GET http://localhost:4741/users \
  --header "Authorization: Token token=$TOKEN"

TOKEN=33ad6372f795694b333ec5f329ebeaaa scripts/users.sh

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "users": [
    {
      "id": 2,
      "email": "another@example.email"
    },
    {
      "id": 1,
      "email": "an@example.email"
    }
  ]
}

GET /users/:id

Request:

curl --include --request GET http://localhost:4741/users/$ID \
  --header "Authorization: Token token=$TOKEN"

ID=2 TOKEN=33ad6372f795694b333ec5f329ebeaaa scripts/user.sh

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "user": {
    "id": 2,
    "email": "another@example.email"
  }
}

License

1. All content is licensed under a CC­BY­NC­SA 4.0 license.
2. All software code is licensed under GNU GPLv3. For commercial use or alternative licensing, please contact legal@ga.co.