REST in Peace #DevoxxPL 2016 talk

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

C84901471a3d6c401c37239dda64c6ff?s=128

Clemens Prerovsky

June 23, 2016
Tweet

Transcript

  1. REST in Peace Clemens Prerovsky @blacktarmac getmesh.io gentics.com

  2. GET /years/2008

  3. None
  4. GET getmesh.io api-first cms

  5. Fielding Roy T.

  6. REST

  7. None
  8. a-ha!

  9. None
  10. OMG Top 10 Tips to R EST in Peace Spoiler

    alert: +1 Bonus Topic
  11. Endpoint Naming 1

  12. None
  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.

  28. None
  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” }
  59. None
  60. 550e8400-e29b-11d4-a716-446655440000 also ok: UUIDs.

  61. Use UUIDs. (Unique Unicorn IDs)

  62. REST Clients Bonus!

  63. None
  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