Scratchbook API

Scratchbook

An API to store users and albums for a music scrapbook app.

It allows players to register as users of the API and add information for their favorite albums.

The API validates unique artist/album cominations, as well as unique username/email combinations.

API end-points

Verb	URI Pattern	Controller#Action
POST	/sign-up	users#signup
POST	/sign-in	users#signin
DELETE	/sign-out/:id	users#signout
PATCH	/change-password/:id	users#changepw
GET	/users/:user_id/albums	albums#index
POST	/users/:user_id/albums	albums#create
GET	/users/:user_id/albums/new	albums#new
GET	/albums/:id/edit	albums#edit
GET	/albums/:id	albums#show
PATCH	/albums/:id	albums#update
PUT	/albums/:id	albums#update
DELETE	/albums/:id	albums#destroy
GET	/users	users#index
GET	/users/:id	users#show
All data returned from API actions is formatted as JSON.

---

User actions

Summary:

Request			Response
Verb	URI	body	Status	body
POST	`/sign-up`	credentials	201, Created	user
			400 Bad Request	empty
POST	`/sign-in`	credentials	200 OK	user w/token
			401 Unauthorized	empty
DELETE	`/sign-out/:id`	empty	201 Created	empty
			401 Unauthorized	empty
PATCH	`/change-password/:id`	passwords	204 No Content	user w/token
			400 Bad Request	empty

signup

The create action expects a POST of credentials identifying a new user to create, e.g. using getFormFields:

<form>
  <input name="credentials[username]" type="text" value="an example username">
  <input name="credentials[email]" type="text" value="[email protected]">
  <input name="credentials[password]" type="password" value="an example password">
  <input name="credentials[password_confirmation]" type="password" value="an example password">
</form>

or using JSON:

{
  "credentials": {
    "username": "an example username",
    "email": "[email protected]",
    "password": "an example password",
    "password_confirmation": "an example password"
  }
}

The credentials[username], credentials[password], and credentials[password_confirmation] fields are sanitized. credentials[email] uses pattern="^[a-zA-Z][a-zA-Z0-9-_\.]{1,20}$", and credentials[password], and credentials[password_confirmation] use pattern="^(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?!.*\s).*$">

The password_confirmation field is optional.

If the request is successful, the response will have an HTTP Status of 201, Created, and the body will be JSON containing the id and email of the new user, e.g.:

{
  "user": {
    "email": "[email protected]",
    "id": 1,
    "username": "an exmaple username"
  }
}

If the request is unsuccessful, the response will have an HTTP Status of 400 Bad Request, and the response body will be empty.

signin

The signin action expects a POST with credentials identifying a previously registered user, e.g.:

<form>
  <input name="credentials[email]" type="text" value="[email protected]">
  <input name="credentials[password]" type="password" value="an example password">
</form>

or:

{
  "credentials": {
    "email": "[email protected]",
    "password": "an example password"
  }
}

If the request is successful, the response will have an HTTP Status of 200 OK, and the body will be JSON containing the user's id, email, and the token used to authenticate other requests, e.g.:

{
  "user": {
    "id": 1,
    "email": "[email protected]",
    "token": "an example authentication token",
    "username": "an example username"
  }
}

If the request is unsuccessful, the response will have an HTTP Status of 401 Unauthorized, and the response body will be empty.

signout

The signout actions is a DELETE specifying the id of the user so sign out.

If the request is successful the response will have an HTTP status of 204 No Content.

If the request is unsuccessful, the response will have a status of 401 Unauthorized.

changepw

The changepw action expects a PATCH of passwords specifying the old and new.

If the request is successful the response will have an HTTP status of 204 No Content.

If the request is unsuccessful the reponse will have an HTTP status of 400 Bad Request.

---

The sign-out and change-password requests must include a valid HTTP header Authorization: Token token=<token> or they will be rejected with a status of 401 Unauthorized.

Album actions

All album action requests must include a valid HTTP header Authorization: Token token=<token> or they will be rejected with a status of 401 Unauthorized.

README still in progress - 5/3/2016