This document discusses API design principles for the modern web. It covers topics such as URI design, representing resources and containers, and using HATEOAS to allow discoverability. Well-designed URIs should be short, semantic, and avoid duplicating data included in HTTP requests. Resources map to URIs and handle data containers and types. Containers wrap data and can represent collections or individual items. The document provides examples of GET, POST, and DELETE requests acting on container resources.

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