This document discusses best practices for creating RESTful APIs. It covers three main topics: representing resources with URLs and HTTP verbs, using the HTTP protocol machinery like status codes and caching, and linking resources together through hypermedia. URLs should represent resources, verbs should represent actions, and standard HTTP features like status codes and conditional requests should be used. Well-designed REST APIs represent application state through linked resources and relationships rather than embedding actions in URLs.

1. CREATING TRULY RESTFUL APIS
BY @DOMENIC

2. A STORY IN THREE PARTS
1. URLs = Resources; Verbs = Actions
2. Using the HTTP Machinery
3. Linking

3. URLS = RESOURCES; VERBS = ACTIONS

4. RESOURCE ARCHETYPES: DOCUMENT
 Think “object instance” or “database record.”
 Examples:
 /partnerships/1234
 /partnerships/1234/funds/ABCD
 /users/0987
 /users/0987/settings
 Typical verbs:
 GET — retrieves the document
 DELETE — deletes the document
 PATCH — performs a partial update of the document
 PUT — creates or updates the document (see upcoming slides)
 Documents can be organized into either collections or stores

5. RESOURCE ARCHETYPES: COLLECTION
 A server-managed resource directory
 Clients may propose addition to the directory, but the server decides the result
 Examples:
 /partnerships
 /partnerships/1234/funds
 /users
 Typical verbs:
 GET /collection — a listing of the whole collection, either inline or as links
 POST /collection — creates a new document, and returns you a link to it
 PUT /collection/document — replaces an existing document
 GET, PATCH, DELETE /collection/document

6. RESOURCE ARCHETYPES: STORE
 A client-managed resource repository
 Examples:
 /users/0987/favorite-funds
 /partnerships/1234/metadata
 Documents exist under stores:
 /users/0987/favorite-funds/ABCD
 /partnerships/1234/metadata/investment-preferences
 Typical verbs:
 GET /store — a listing of the whole store, either inline or as links
 PUT /store/document — creates or replaces the document
 GET, PATCH, DELETE /store/document

7. DOMAIN MODELING WITH RESOURCES
 URLs are always nouns, never actions:
 Find distance between points: GET /distance?point1=x&point2=y
 Discount this item’s price by 15%:
 PUT /item/discount { percent: 15 }
 or PUT /discounts/itemID { percent: 15 } if discounts are a primary entity in your domain
 Hierarchical URL structure represents hierarchy of resources in your domain
 Not just stores and collections: /user/0987/settings; /user/0987/pictures/large; etc.
 Query parameters represent filtering, sorting, and projections
 Extra verbs:
 HEAD lets you interrogate for certain metadata, e.g. Content-Length
 OPTIONS lets you find out what verbs are supported, e.g. “is this document deletable?”

8. USING THE HTTP MACHINERY

9. STATUS CODES: THE BASICS
There’s life beyond 200, 404, and 500!
 100, 101 = meta stuff; don’t worry about it
 2xx = success
 3xx = redirection: further action may be needed
 4xx = client error: user screwed up
 5xx = server error: server screwed up
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

10. SAMPLE SIMPLE STATUS CODE USES: GET AND DELETE
 GET /partnerships/1234/funds/ABCD
 200 OK
 301 Moved Permanently: the fund has been transferred to another partnership
 401 Unauthorized: you need to authenticate first
 403 Forbidden: you’re authenticated, but not authorized
 404 Not Found: no such fund exists under this partnership
 DELETE /document
 204 No Content

11. SAMPLE SIMPLE STATUS CODE USES: PUT AND POST
 PUT /store/document
 200 OK: old document overwritten
 201 Created: new document created
 409 Conflict: you tried to overwrite the document but you didn’t have the latest version
 POST /collection
 201 Created: new document created
 303 See Other: a document with that name (or whatever) already existed
 Either case:
 400 Bad Request: data did not pass validation
 401, 403: as before
 413 Request Entity Too Large: you tried to upload too large of a document
 415 Unsupported Media Type: you tried to upload a PDF, but we only support text files

12. OTHER IMPORTANT MACHINERY
 Caching
 Client-side caching via Cache-Control and Expires headers
 Conditional GETs to avoid downloading again
 Conditional updates to avoid conflicts
 Content negotiation to serve the correct representation of a resource
 Range requests for downloading chunks from a larger document
 Metadata headers: Content-Type, Content-Length, Etag, …
 Authorization header
Takeaway: no need to build envelopes or protocols on top of HTTP; it has the tools you need

13. LINKING

14. HYPERTEXT AS THE ENGINE OF APPLICATION STATE
 Your API should advertise a single entry point, e.g. https://api.lab49.com
 From there, links direct you to desired resources
 Links are specified by relationship types, or rels.
 There are standard rels, e.g. prev, next, parent, self, etc.
 But most relationships are domain-specific, telling you how to get to an interesting resource
 Clients do not know resource URLs
 They know the single entry point URL
 They know the rels of resources they are interested in
 They know how to navigate from resource to resource

15. EXAMPLE: GET /
{
"_links": {
"http://rels.api.lab49.com/partnerships": { "href": "/partnerships" },
"http://rels.api.lab49.com/users": { "href": "/users" }
}
}

16. EXAMPLE: GET /PARTNERSHIPS
{
"_links": {
"http://rels.api.lab49.com/partnership": [
{ "href": "/partnerships/1234" },
{ "href": "/partnerships/4321" },
{ "href": "/partnerships/3142" }
]
}
}

17. EXAMPLE: GET /PARTNERSHIPS/1234
{
"_links": {
"http://rels.api.lab49.com/funds": { "href": "/partnerships/1234/funds" }
},
"name": "Denicola Global Management",
"type": "GP",
"missionStatement": "To make lots of money"
}

18. WRAP-UP

19. THINGS WE DON’T HAVE TIME FOR
 Controller resources
 Embedded resources
 API versioning schemes
 Authentication, e.g. with OAuth 2
 Data formats, e.g. how to format PATCH data or hypermedia links
 Playing nice with proxies
 HTTPbis

20. THINGS YOU SHOULD READ
 HTTPbis: Semantics and Content (and the others)
 RESTful Web Services Cookbook by Subbu Allamaraju
 REST API Design Rulebook by Mark Masse
 Hypertext Application Language (HAL) spec