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.


Clemens Prerovsky

June 23, 2016


  1. REST in Peace Clemens Prerovsky @blacktarmac

  2. GET /years/2008

  3. None
  4. GET 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


  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.


  68. Thank you! @genticsmesh +43 1 7109904-0 @blacktarmac REST in Peace!
  69. Resources Best Practices for Designing a Pragmatic RESTful API

    REST API Design with Brian Sletten REST+JSON API Design - Best Practices for Developers Securing API Keys in a JavaScript Single Page App javascript-single-page-app/ REST Security Cheat Sheet The art of innovation | Guy Kawasaki | TEDxBerkeley The Fundamentals of REST API Design 10 Best Practices for Better RESTful API restful-api/ REST WORST PRACTICES API Versioning Architectural Styles and the Design of Network-based Software Architectures Stop Comparing JSON and XML Stop Writing REST API Clients
  70. Images “The Triumph of Death” by Pieter Bruegel the Elder,

    1562 inspired by Photo of Sad Puppy by Matthew Wiebe “Wildweibchen mit Einhorn”, Unknown Artist “First World Problems MEME”, Unknown Artist Photo of Marie Curie, Unknown Artist Hedgehog Belly Rub, Unknown Artist, via Reddit “Botón Me gusta” by Enoc vt “Chuck Norris PSD” by xzeroherox “Fry Not Sure MEME”, Unknown Artist
  71. REST in Peace Clemens Prerovsky +43 1 7109904-0