API Design

WHY?

- Discoverability- Scalability- Permanency

WHAT?

- Easy to use- Minimal Requests- Maximum data (BIG DATA)

HOW?

- URL- RESOURCE

- CONTAINER- LINKAGE- DOCUMENTATION

Structure

/album_arts

/album_arts/:album

/album_arts/:album/alternate

dsotm.jpg

/artists

/artists/1

/artists/1?include=cds

/cds

/cds/1

/cds?artist=1

/cds/1?include=artist

dsotm_b.jpg

URI

- short- Semantic- Easily understood- No duplication of data with HTTP- Pluralized- Nouns

URI

- /account.cgi?user_id=12234

- /view_vacancy.cgi?response_id=1234

- /account/1.json- /account/1?

op=delete

- /users/12234?include=preferences

- /responses/1234

URI

- /board/1/responses

- Only if relationship solely within parent

- /responses?board=1

- All other instances

URL

/:container/:id?:filter_query

/:container/:id/:subcontainer|:function

Filter Query

- Include => Return a related resource- Attributes => Filter on this attribute- Fields => Only return the named fields- Count => Number of items to return- Page => Page to return- Sort => Sort metric

Resources & Containers

- Resource is a Handler- Resources are mapped to URIs- Container is the Data of a Resource- 1 resource handles 1 container type- Container might be Collection or Item

Containers

- A User- Accounts- Javascript file- Images- WebPage- Git commit

Resource

- Handles logic for getting Containers- Handles logic for serializing containers- Similar to a controller in MVC- Handles HTTP

HATEOAS- Link webpage browsing- Link other resources- Allows discoverability- HTTP defines change

Container - GET{

“artists”: [{

“id”: 1“name”: “Pink Floyd”,“_links”: {

“cds”: “/cds?artist=1}

}]

}

GET HTTP/1.1 /artists

Accept: application/json

---200 OKContent-Type: application/json

Container - POSTPOST HTTP/1.1 /artists

Content-Type: application/json

---204 No Content

Location /artists/2

{“name”: “Pink Floyd”,“cds”: [{

“name”: “dsotm”}]

}

Container - DeleteDELETE HTTP/1.1 /artists

--

204 No Content

GET HTTP/1.1 /artists/1

Accept: application/json

--

410 Gone