REST my dongle #kreait-dev-days

REST best practices, HAL, HATEOAS

Transcript

1. Logitech R400
2. Slide 1
3. Slide 2
4. GET /slides
5. [ { "id": 1, "content": "Slide 1" }, { "id": 2, "content": "Slide 2" }, ]
6. GET /slide/1
7. { "id": 1, "content": "Slide 1", "background": "white", "text": "#031337" }
8. Verb Method GET /slides Get list of slides C POST /slides Create new slide R GET /slides/:id Get specific slide U PUT /slides/:id Update slide D DELETE /slides/:id Delete slide
9. Next Previous
11. 1. GET /slides 2. Remember IDs 3. Figure out index 4. index++ 5. GET /slides/2
12. GET /slides/1/next GET /nextSlide/1
13. REST Maturity Model
14. HATEOAS (Hypertext As The Engine Of Application State) Level 3: Hypermedia HAL (Hypertext Application Language)
15. { "id": 5, "content": "Slide 1", "background": "white", "text": "#031337" "_links": { "self": { "href": "/slides/5" }, "prev": { "href": "/slides/4" }, "next": { "href": "/slides/6" }, "first": { "href": "/slides/1" }, "last": { "href": "/slides/12" } } }
16. HAL + JSON http://stateless.co/hal_specification.html
17. R(B)EST practices
18. 1. Do not use verbs /getAllSlides /createNewSlide /deleteAllBlackSlides GET /slides POST /slides DELETE /slides?filter=black
19. 2. GET method should NEVER alter the state GET /slide/1?action=disable POST /slides/1/disable or PUT /slides/1/disable
20. 3. Use plural nouns /slide /slides
21. 4. Use sub-resources for relations GET /animationsForSlide/1 DELETE /animationsFromSlide/1/2 GET /slides/1/animations/ DELETE /slides/1/animations/3
22. 5. Use HTTP headers for serialization formats Content-type: application/vnd+com.kreait.slide+json
23. 6. Use HAL { "id": 1, "content": "Slide 1", "background": "white", "text": "#031337" "_links": { "self": { "href": "/slides/1" }, "next": { "href": "/slides/2" } } }
24. 7. Filtering, Sorting, field selection and paging Filter GET /slides?background=white Sort GET /slides?sort=-title,+length Limit Fields GET /slides?fields=id,title Pagination GET /slides?offset=10&limit=5
25. 8. Version your API In URL: /api/v1/slides
26. 9. Handle Errors with HTTP status codes http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html and https://github.com/joho/7XX-rfc Errors in vnd.error format (https://github.com/blongden/vnd.error) or at least something consistent
27. 10. Allow overriding HTTP method X-HTTP-Method-Override: PUT
28. Dongle included Thanks!