Api design
-
Upload
michael-francis -
Category
Software
-
view
140 -
download
6
Transcript of Api design
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