REST+JSON API Key Points

REST-JSON-API.md

#REST+JSON API

Credit to https://stormpath.com/blog/designing-rest-json-apis/

##Behavior

PUT and POST can both be used for Create and Update

PUT for Update

Idempotent - full replacement on Update, even if you change a single property

PUT /application/exisitingId
{
  "name": "Best App Ever",
  "description": "Awesomeness"
}

POST for Update

NOT Idempotent

POST /application/a1b2c3
{
  "name": "Best App Ever. Srsly"
}

Response:
200 OK

##Media Types

• Format Specification + Parsing Rules
• Request: Accept header
• Response: Content-Type header
• application/json
• application/foo+json
• application/foo+json;application

##Design

Simple

http(s)://api.foo.com/v1

Allow Rest Client and Browser to both property interpret the URL

##Date/Time/Timestamp

Use the standard ISO 8601 and UTC Timezone

{
  "createdTimestamp": "2014-04-19T18:02:24.343Z"
}

##HREF

Every accessible Resource has a canonical unique URL

GET /accounts/x7y8z9

200 OK
{
  "href": "https://api.foo.com/v1/accounts/x7y8z9",
  "firstName": "Tony",
  "lastName": "Stark"
}

Linking

GET /accounts/x7y8z9

200 OK
{
  "href": "https://api.foo.com/v1/accounts/x7y8z9",
  "firstName": "Tony",
  "lastName": "Stark",
  "directory": {
    "href": "https://api.foo.com/v1/directories/g4h5i6"
  }
}

Reference Expansion

GET /accounts/x7y8z9?expand=directory

200 OK
{
  "href": "https://api.foo.com/v1/accounts/x7y8z9",
  "firstName": "Tony",
  "lastName": "Stark",
  "directory": {
    "href": "https://api.foo.com/v1/directories/g4h5i6",
    "name": "Avengers",
    "description": "Hollywood's hope for more $",
    "creationDate": "2014-04-19T18:02:24.343Z"
  }
}

Partial Representations

GET /accounts/x7y8z9?fields=firstName,lastName,directory(name)

##Errors

POST /directories

409 Conflict
{
  "status": 409,
  "code": 40924,
  "property": "name",
  "message": "A directory named 'Avengers' already exists.",
  "developerMessage": "A directory named 'Avengers' already exisits. If you have a stale local cache, please expire it now.",
  "moreInfo": "https://www.stormpath.com/docs/api/errors/40924"
}