A template for starting projects with rails-api. Includes authentication.

At the beginning of each cohort, update the versions in Gemfile.

Install with bundle install.

• rails-api
• rails
• active_model_serializers
• ruby
• postgres

Until Rails 5 is released, this template should follow the most recent released version of Rails 4, as well as track master branches for rails-api and active_model_serializers.

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. Install dependencies with bundle install.
6. Rename your app module in config/application.rb (change RailsApiTemplate).
7. Rename your project database in config/database.yml (change 'rails-api-template').
8. Create a .env for sensitive settings (touch .env).
9. Generate new development and test secrets (bundle exec rake secret).
10. Store them in .env with keys SECRET_KEY_BASE_<DEVELOPMENT|TEST> respectively.
11. In order to make requests from your deployed client application, you will need to set CLIENT_ORIGIN in the environment of the production API (e.g. https://<github-username>.github.io).
12. Setup your database with bin/rake db:nuke_pave or bundle exec rake db:nuke_pave.
13. Run the API server with bin/rails server or bundle exec rails server.

This template follows the standard project structure in Rails 4.

curl command scripts are stored in scripts with names that correspond to API actions.

User authentication is built-in.

Developers should run these often!

• rake routes lists the endpoints available in your API.
• rake test runs automated tests.
• rails console opens a REPL that pre-loads the API.
• rails db opens your database client and loads the correct database.
• rails server starts the API.
• scripts/*.sh run various curl commands to test the API. See below.

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. As an alternative, you can write automated tests in RSpec to test your API.

Request:

curl --include --request POST http://localhost:3000/sign-up \
  --header "Content-Type: application/json" \
  --data '{
    "credentials": {
      "email": "[email protected]",
      "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": "[email protected]"
  }
}

Request:

curl --include --request POST http://localhost:3000/sign-in \
  --header "Content-Type: application/json" \
  --data '{
    "credentials": {
      "email": "[email protected]",
      "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": "[email protected]",
    "token": "33ad6372f795694b333ec5f329ebeaaa"
  }
}

Request:

curl --include --request PATCH http://localhost:3000/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

Request:

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

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

Response:

HTTP/1.1 204 No Content

Request:

curl --include --request GET http://localhost:3000/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": "[email protected]"
    },
    {
      "id": 1,
      "email": "[email protected]"
    }
  ]
}

Request:

curl --include --request GET http://localhost:3000/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": "[email protected]"
  }
}

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 [email protected].