The never-ending REST API design debate by Guillaume Laforge

What should a good REST API look like? Should you use verbs or nouns in your resource paths? How do you handle versioning of APIs? How to deal with partial responses and pagination? Which status codes should I make use of? What about sorting, filtering, and searching? Have you thought about content negotiation, cross-domain access, hypermedia, and authentication?

Guillaume will got through all these topics, offering advice on the best approaches to those questions, and opening up the debate on the various options available, so as to make your Web API at REST, as clean and elegant as possible.

[ruixue]

5:41 GET POST PUT DELET
6:46 POST
6:52 PUT
7:34 Nouns are good, verbs are bad
9:35 naming
9:50 prefer plural forms
10:24 less confusing to use plural form
12:35 using snake case is more readable than using camel case
13:16 dealing with relations in your URLs
13:47 the trick is to think in terms of whether the sub-resource stands on its own
15:11 API parameters Rule of Thumb
15:18 Path - 16:05 parameter for identifying resource
15:33 Query - ?id=43 16:15 sth that refines Optional, e.g. query collection - filter a collection
15:41 Body - 16:27 when there is some advanced logic going on, 16:30 when you want to send a search query
15:47 Header
17:11 HTTP status code map
18:29 1XX - Hold on ... there is more to come
18:34 2XX - Here you go
18:40 3XX - redirection ro sth, just go away
18:46 4XX - you fucked up
18:52 5XX - I fucked up
20:21 200 - Create!
　21:05 API navigation is more important to make API more discoverable
24:05 200 - Accepted
24:36 204 - no content - DELETE
25:18 206 - partial content -> pagination
26:15 304 - not modified
28:24 pagination
30:40 with accept range header
31:48 wrapped collections
33:53 3XX
34:19 4XX
34:41 429 too many request
38:38 different payloads for different consumers
39:08 filtering
39:34 specify fields
39:58 specify exclude fields
40:10 specify style
43:02 sort
44:07 searching
44:40 versioning
46:27 hypermedia
48:03 pros & cons for hypermedia
52:02 change is unavoidable
55:10 HAL approach

[danielkrajnik]

4:23 its been like what 3 years until I understood what representations stood for...

[coolcoolj]

boring representation style but useful information