Jcornmanhomonoff/rx-back

Rails

rx-back

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/rx-back-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 rx-back).
3. Rename your project database in config/database.yml (change 'rx-back').

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: Remember to follow the same commands when setting up your deployed database!

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 scripts with names that correspond to API actions.

User authentication is built-in.

Tasks

Developers should run these often!

• bin/rails routes lists the endpoints available in your API.
• bin/rails test runs automated tests.
• 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.
• 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 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

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 scripts/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 scripts/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 scripts/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 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
PATCH	/users/1	users#update

GET /users

Request:

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

TOKEN=BAhJIiVlZDIwZTMzMzQzODg5NTBmYjZlNjRlZDZlNzYxYzU2ZAY6BkVG--7e7f77f974edcf5e4887b56918f34cd9fe293b9f scripts/users.sh

Response:

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

{
  "users": [
    {
      "id": 2,
      "email": "bob@ava.com"
    },
    {
      "id": 1,
      "email": "ava@bob.com"
    }
  ]
}

GET /users/:id

Request:

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

ID=2 TOKEN=BAhJIiVlZDIwZTMzMzQzODg5NTBmYjZlNjRlZDZlNzYxYzU2ZAY6BkVG--7e7f77f974edcf5e4887b56918f34cd9fe293b9f scripts/user.sh

Response:

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

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

PATCH /users/:id

Request:

curl "http://localhost:4741/users/${ID}" \
  --include \
  --request PATCH \
  --header "Authorization: Token token=${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "user": {
      "email": "'"${EMAIL}"'"
    }
  }'

ID=1 TOKEN="BAhJIiU1NGNlYjRmMjBhM2NkZTZiNzk1MGNiYmZiYWMyY2U4MwY6BkVG--ddb1e16af0e05921aa56d771e4a2f816f2a1d46e"
EMAIL=mike@m
sh scripts/users/user-update.sh

Response:

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

{"user":{"id":1,"email":"mike@m"}}

Reset Database without dropping

This is not a task developers should run often, but it is sometimes necessary.

locally

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

heroku

heroku run rails db:migrate VERSION=0
heroku run rails db:migrate db:seed db:examples

Additional Resources

• rails-heroku-setup-guide
• http://guides.rubyonrails.org/api_app.html
• https://blog.codeship.com/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.