library-api-guide

A simple API for books.

Installation

1. Fork and clone this repository.

2. Change into the new directory.

3. Install dependencies with bundle install.

4. Create a .env for sensitive settings (touch .env).

5. Generate new different secrets for both development and test environments (bundle exec rake secret).

6. Store them in .env with keys SECRET_KEY_BASE_<DEVELOPMENT|TEST> respectively.

7. Create a database with bundle exec rake db:create.

8. Create a database schema with bundle exec rake db:migrate.

9. Add data to the database with bundle exec rake db:seed db:examples.

10. Run the HTTP server with bundle exec rails server or bin/rails server.

Structure

library-api-guide follows the standard project structure for Rails 4.

User authentication is built-in.

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

Tasks

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

API

books

Verb	URI Pattern	Controller#Action
GET	/books	books#index
GET	/books/:id	books#show
POST	/books	books#create
PATCH	/books/:id	books#update
DELETE	/books/:id	books#destroy

GET /books

GET /books/:id

POST /books

PATCH /books/:id

DELETE /books/:id

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"
  }
}

Reset Database without dropping

• locally

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

• heroku

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

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.