Rails

rails-api-template

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

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

Prerequisites

• rails-api-examples-walkthrough

Dependencies

Install with bundle install.

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

Installation

Download Template:

1. Download this template.
2. Unzip and rename the template directory (unzip ~/Downloads/rails-api-template-master.zip)
3. Move into the new project and git init.

Customize Template:

1. Empty README.md and fill with your own content.
2. Rename your app module in config/application.rb (change RailsApiTemplate).
3. Rename your project database in config/database.yml (change 'rails-api-template').

Setup Environment:

1. Install dependencies with bundle install.
2. git add and git commit your changes.
3. Create a .env for sensitive settings (touch .env).
4. Generate new development and test secrets (bundle exec rails secret).
5. Store them in .env with keys SECRET_KEY_BASE_<DEVELOPMENT|TEST> respectively.
6. In order to make requests to your deployed API, you will need to set SECRET_KEY_BASE in the environment of the production API (for example, using heroku config:set or the Heroku dashboard).
7. In order to make requests from your deployed client application, you will need to set CLIENT_ORIGIN in the environment of the production API (for example, heroku config:set CLIENT_ORIGIN=https://<github-username>.github.io). See more about deploying to heroku rails-heroku-setup-guide

Setup your database:

- bin/rails db:drop (if it already exists)
- bin/rails db:create
- bin/rails db:migrate
- bin/rails db:seed
- bin/rails db:examples

Note: Do this for each database you want to set up. Your local database and production (Heroku) database will both need to be set up in this way!

Run your server!

1. Run the API server with bin/rails server or bundle exec rails server.

Structure

This template follows the standard project structure in Rails.

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

User authentication is built-in.

Tests (also called specs) are located in the spec folder.

Tasks

Developers should run these often!

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

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 curl-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.

Authentication Endpoints and Curl Scripts

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

POST /sign-up

Request:

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

EMAIL=ava@bob.com PASSWORD=hannah curl-scripts/auth/sign-up.sh

Response:

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

{
  "user": {
    "id": 1,
    "email": "ava@bob.com"
  }
}

POST /sign-in

Request:

curl http://localhost:4741/sign-in \
  --include \
  --request POST \
  --header "Content-Type: application/json" \
  --data '{
    "credentials": {
      "email": "'"${EMAIL}"'",
      "password": "'"${PASSWORD}"'"
    }
  }'

EMAIL=ava@bob.com PASSWORD=hannah curl-scripts/auth/sign-in.sh

Response:

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

{
  "user": {
    "id": 1,
    "email": "ava@bob.com",
    "token": "BAhJIiVlZDIwZTMzMzQzODg5NTBmYjZlNjRlZDZlNzYxYzU2ZAY6BkVG--7e7f77f974edcf5e4887b56918f34cd9fe293b9f"
  }
}

PATCH /change-password

Request:

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

OLDPW='hannah' NEWPW='elle' TOKEN='BAhJIiVlZDIwZTMzMzQzODg5NTBmYjZlNjRlZDZlNzYxYzU2ZAY6BkVG--7e7f77f974edcf5e4887b56918f34cd9fe293b9f' sh curl-scripts/auth/change-password.sh

Response:

HTTP/1.1 204 No Content

DELETE /sign-out

Request:

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

TOKEN='BAhJIiVlZDIwZTMzMzQzODg5NTBmYjZlNjRlZDZlNzYxYzU2ZAY6BkVG--7e7f77f974edcf5e4887b56918f34cd9fe293b9f' sh curl-scripts/auth/sign-out.sh

Response:

HTTP/1.1 204 No Content

Keeping your database up to date

Remember, creating and applying migrations are two different things. After you create a migration (one of those files that lives in db/migrate/), you need to apply it to each database using bin/rails db:migrate (local) or heroku run rails db:migrate (production).

Rolling Back a Database Migration

Sometimes you need to revert a migration that you already applied. There are many ways to revert your database to a previous state, and one of the most common is simply rolling back (reverting) the last migration that you ran. Read more in the Rails Guide

Reset Database without dropping

If you don't want to completely reset the database (maybe you have data you want to preserve?), you have other, less destructive options. One is rolling back a specific migration by specifying the VERSION that the database should revert to. Ask a consultant if you need assistance, as database commands like these are non-reversable.

To rerun all migrations, starting from VERSION=0, you would do:

bin/rails db:migrate VERSION=0
bin/rails db:migrate db:seed db:examples

To run this command (and others like this) on Heroku, just append heroku run before the rails command.

Additional Resources

• rails-heroku-setup-guide
• Rails Guides: API-only app
• Building a JSON API with Rails 5

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.