REST in Peace #DevoxxPL 2016 talk

REST APIs are the language of the web. Though simple to build, it's also very easy to mess them up. You end up with a convoluted API, that's hard to understand and even worse to use. I want to show you how to create REST APIs that are both comprehensible are maintainable and make your fellow developers happy.

https://www.youtube.com/watch?v=c0nQEwfKlsM

Transcript

1. REST in Peace Clemens Prerovsky @blacktarmac getmesh.io gentics.com
2. GET /years/2008
4. GET getmesh.io api-first cms
5. Fielding Roy T.
6. REST
8. a-ha!
10. OMG Top 10 Tips to R EST in Peace Spoiler alert: +1 Bonus Topic
11. Endpoint Naming 1
13. /getAllNodes GET
14. GET /nodes plural
15. POST /nodes GET /nodes PUT /nodes DELETE /nodes Now we’re able to...
16. Use plural nouns.
17. GET /search … is the of REST resources
18. HTTP Verbs 2
19. POST GET PUT DELETE create read update delete
20. POST both work for create & update & PUT { “firstname”: “clemens” } { “id”: “da796a”, “firstname”: “clemens”, “lastname”: “prerovsky”, … } partial data complete data
21. PUT is idempotent. use fancy word
22. HEAD OPTIONS PATCH TRACE
23. Cater to your audience.
24. Subresources 3
25. GET /nodes/de2c75 tag
26. ?node_id=de2c75 GET /tags GET /nodes/de2c75/tags subresource
27. Express relations with subresources.
29. { “likes”: [“user1”, “user2”, …] }
30. POST /nodes/de2c75/like action subresource GET, PUT, DELETE &
31. Data Formats 4
32. Use JSON. “ ― Marie Curie Seriously dude, XML will make your hair fall out.
33. Decide for one output format.
34. Models & Resouces 5
35. GET / { “id”: 42 “_hidden”: true { <? { “.”: “!” “.deprecated_id”
36. Go! Design your API like a UI
37. Carefully craft your API. Don’t just re-implement your model!
38. Status Codes 6
39. GET /a*!%uh-LOL-WUT?42 HTTP/1.1 200 OK
40. HTTP 400s HTTP 500s you messed up we messed up
41. GET /ndoes HTTP/1.1 404 Not Found { “message”: “Not Found”, “description”: “We could not find an API endpoint named ‘ndoes’.” } provide body & description
42. Use correct HTTP status codes.
43. Path Parameters & Resources 7
44. GET /news/2016/may/breadcrumb
45. GET /folders/news/2016/may GET /breadcrumbs/news/2016/may
46. Never mix parameters and resources.
47. API Versioning 8
48. GET /api/v1/nodes vs. Accept: application/json; version=1.0
49. GET /api/v1/… $.getJSON( '/api/v1/nodes', success ); Accept: $.ajax({ url: '/nodes, headers: { Accept: 'application/json; version=1.0' } }).done(success); vs.
50. Enable browser access.
51. GET /api/v13.8.57/nodes v2 major versions only!
52. State 9
53. POST /schemas/de2c75/migrations/init POST /schemas/de2c75/migrations/dryrun POST /schemas/de2c75/migrations/run GET /schemas/de2c75/migrations/status POST /schemas/de2c75/migrations/commit All the NOPE.
54. …/init …/dryrun …/run …/status …/commit …/diff …/migrations
55. Don’t be chatty. Be stateless.
56. IDs 10
57. { “id”: 42 }
58. { “id”: 42 “name”: “blog” } { “id”: 42 “name”: “news” }
60. 550e8400-e29b-11d4-a716-446655440000 also ok: UUIDs.
61. Use UUIDs. (Unique Unicorn IDs)
62. REST Clients Bonus!
64. auto- gen generic grade of automation none roll your ow n coding effort GUARANTEE BEST VALUE
65. Be minimalist Be consistent Be your customer
66. plz vote every time you don’t vote a puppy dies.
67. getmesh.io
68. Thank you! getmesh.io @genticsmesh gentics.com +43 1 7109904-0 c.prerovsky@gentics.com @blacktarmac www.gentics.com REST in Peace!
69. Resources Best Practices for Designing a Pragmatic RESTful API http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api REST API Design with Brian Sletten https://www.youtube.com/watch?v=HW9wWZHWhnI REST+JSON API Design - Best Practices for Developers https://www.youtube.com/watch?v=hdSrT4yjS1g Securing API Keys in a JavaScript Single Page App http://billpatrianakos.me/blog/2016/02/15/securing-api-keys-in-a- javascript-single-page-app/ REST Security Cheat Sheet https://www.owasp.org/index.php/REST_Security_Cheat_Sheet The art of innovation | Guy Kawasaki | TEDxBerkeley https://www.youtube.com/watch?v=Mtjatz9r-Vc The Fundamentals of REST API Design https://stormpath.com/blog/fundamentals-rest-api-design 10 Best Practices for Better RESTful API http://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better- restful-api/ REST WORST PRACTICES https://jacobian.org/writing/rest-worst-practices/ API Versioning http://symfony.com/doc/current/bundles/FOSRestBundle/versioning.html Architectural Styles and the Design of Network-based Software Architectures http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm Stop Comparing JSON and XML http://www.yegor256.com/2015/11/16/json-vs-xml.html Stop Writing REST API Clients http://ttezel.github.io/blog/2013/02/23/stop-writing-rest-api-clients/
70. Images “The Triumph of Death” by Pieter Bruegel the Elder, 1562 https://upload.wikimedia.org/wikipedia/commons/1/10/Thetriumphofdeath.jpg inspired by http://classicprogrammerpaintings.com/ Photo of Sad Puppy by Matthew Wiebe https://unsplash.com/photos/2Ts5HnA67k8 “Wildweibchen mit Einhorn”, Unknown Artist https://commons.wikimedia.org/wiki/File:Wildweibchen_mit_Einhorn.jpg “First World Problems MEME”, Unknown Artist https://imgflip.com/i/15t3ot Photo of Marie Curie, Unknown Artist https://commons.wikimedia.org/wiki/File:Marie_Curie_Tekniska_museet.jpg Hedgehog Belly Rub, Unknown Artist, via Reddit https://www.reddit.com/r/gifs/comments/3l3b6z/hedgehog_is_a_bit_too_happy_with_the_belly_rub/ “Botón Me gusta” by Enoc vt https://en.wikipedia.org/wiki/Facebook_like_button#/media/File:Bot%C3%B3n_Me_gusta.svg “Chuck Norris PSD” by xzeroherox http://www.officialpsds.com/Chuck-Norris-PSD41327.html “Fry Not Sure MEME”, Unknown Artist http://www.socialmemegenerator.com/meme-generator/not-sure-if-fry/
71. REST in Peace Clemens Prerovsky +43 1 7109904-0 c.prerovsky@gentics.com www.gentics.com