Simplistic look at good practices when designing API's

1. API Design
Web design for the modern age

2. sns.amazon.api.
com/Action=publish&Topic=arn.sns.aws.
13232423.
TestTopic&AccessKey=jusghdui873223nkjh&Si
gnatureVersion=2&Signature=213hkh89yh123j
4h&.......
The Problem

3. The Solution
POST
sns.amazon.api.com/topic/TestTopic?
message=123123&subject=123123
Auth: jusghdui873223nkjh
x-auth-version: 2

4. The Spoilers
● URI Design
● Resources
● Containers
● HATEOAS

5. The Words
● RPC - Remote Procedure Call
● REST - Representational State Transfer
● Container - A Data wrapper
● Resource - A request handler
● URL/URI - A Resource identifier

6. RPC - Structure
dsotm.jpg
Controller Controller
dsotm_b.jpg
/update_cd
/update_artist
/get_artist
/get_artist_and_cds
Server -
Static Files

7. 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

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

9. URI - The Bad
- /account.cgi?user_id=12234 # Resource?
- /account/1.json # Data Type
- /account/1?op=delete # Action

10. URI - The Good
- /users # Collection
- /responses/1234 # Item
- ?foo=bar # Filter

11. URI - The Ugly
- /board/1/responses
- Only if relationship
solely within parent
- /responses?board=1
- All other instances

12. URL
/:container/:id?:filter_query
/:container/:id/:subcontainer|:function

13. 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

14. Resources & Containers
- Resource is a Handler
- Resources are mapped to URIs
- Container is the Data wrapper - Data
- 1 resource handles 1 data type
- Container might be Collection or Item

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

16. Resource
- One class per resource type
- Roles for common functions
- Control flow managed by HTTP State

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

18. Containers
- A User
- Accounts
- Javascript file
- Images
- WebPage
- Git commit

19. Container - GET
{
“artists”: [
{
“id”: 1
“name”: “Pink Floyd”,
“_links”: {
“cds”: “/cds?artist=1
}
}
]
}
GET HTTP/1.1 /artists
Accept: application/json
---
200 OK
Content-Type: application/json

20. Container - POST
POST HTTP/1.1 /artists
Content-Type: application/json
---
204 No Content
Location /artists/2
{
“name”: “Pink Floyd”,
“cds”: [{
“name”: “dsotm”
}]
}

21. Container - Delete
DELETE HTTP/1.1 /artists
--
204 No Content
GET HTTP/1.1 /artists/1
Accept: application/json
--
410 Gone