viohlet/time-capsule-api

Bucket-List-API

Front-end client repo: https://github.com/Code-Grace/bucket-list-browser-template Client website: https://code-grace.github.io/bucket-list-browser-template/

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

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.

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://127.0.0.1:3000/sign-up \
  --header "Content-Type: application/json" \
  --data '{
    "credentials": {
      "userName": "user_name",
      "yearOfBirth": "1993",
      "description": "my description",
      "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,
    "userName": "user_name",
    "yearOfBirth": "1993",
    "description": "my description",
  }
}

POST /sign-in

Request:

curl --include --request POST http://127.0.0.1:3000/sign-in \
  --header "Content-Type: application/json" \
  --data '{
    "credentials": {
      "userName": "user_name",
      "password": "an example password"
    }
  }'

scripts/sign-in.sh

Response:

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

{
  "user": {
    "id": 1,
    "userName": "my_name",
    "token": "33ad6372f795694b333ec5f329ebeaaa"
  }
}

PATCH /change-password/:id

Request:

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

DELETE /sign-out/:id

Request:

curl --include --request DELETE http://127.0.0.1:3000/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://127.0.0.1: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,
      "userName": "user_name"
    },
    {
      "id": 1,
      "userName": "user_name"
    }
  ]
}

GET /users/:id

Request:

curl --include --request GET http://127.0.0.1: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,
    "userName": "another@example.userName"
  }
}

Tasks

Verb	URI Pattern	Controller#Action
GET	/tasks	tasks#index
GET	/tasks/$ID	tasks#show
POST	/tasks	tasks#create
PATCH	/tasks/$ID	tasks#update
DELETE	/tasks	tasks#destroy

GET /tasks

Request:

curl --include --request GET http://127.0.0.1:3000/tasks \
  --header "Authorization: Token token=$TOKEN"

TOKEN=33ad6372f795694b333ec5f329ebeaaa scripts/tasks.sh

Response:

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

{
  "tasks": [
    {
      "_id": $ID,
      "title": "title",
      "description": "description",
      "completed": "completed"
    },
    {
      "_id": $ID,
      "title": "title",
      "description": "description",
      "completed": "completed"
    }
  ]
}

GET /tasks/:id

Request:

curl --include --request GET http://127.0.0.1:3000/tasks/$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

{
  "_id": $ID,
  "title": "title",
  "description": "description",
  "completed": "completed"
  }
}

POST /tasks

Request:

curl --include --request POST http://127.0.0.1:3000/tasks \
  --header "Content-Type: application/json" \
  --header "Authorization: Token token=lsYjQw573IuOVbCQYV/QeD9oFeUeZ+zhZZIfxiW8XgU=--uVSLg1CU1k6vgiyaqDiYvUHXzUvrzCWdLT99Fn3+eMg=" \
  --data '{
    "tasks": {
      "title": "my task",
      "description": "my first list"
    }
  }'

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

Response:

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

{
  "_id": $ID,
  "title": "title",
  "description": "description",
  "completed": "completed"
  }
}

PATCH /tasks/$ID

Request:

curl --include --request PATCH http://127.0.0.1:3000/tasks/$ID \
  --header "Content-Type: application/json" \
  --header "Authorization: Token token=lsYjQw573IuOVbCQYV/QeD9oFeUeZ+zhZZIfxiW8XgU=--uVSLg1CU1k6vgiyaqDiYvUHXzUvrzCWdLT99Fn3+eMg=" \
  --data '{
    "tasks": {
      "title": "my updated task",
      "description": "updated",
      "completed": true
    }
  }'

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

Response:

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

{
  "_id": $ID,
  "title": "title",
  "description": "description",
  "completed": "completed"
  }
}

DELETE /tasks/$ID

Request:

curl --include --request DELETE http://127.0.0.1:3000/tasks/$ID \
  --header "Authorization: Token token=lsYjQw573IuOVbCQYV/QeD9oFeUeZ+zhZZIfxiW8XgU=--uVSLg1CU1k6vgiyaqDiYvUHXzUvrzCWdLT99Fn3+eMg=" \

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

Response:

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

{
  "_id": $ID,
  "title": "title",
  "description": "description",
  "completed": "completed"
  }
}

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.