$30 off During Our Annual Pro Sale. View Details »


Honza Javorek
November 20, 2013


How to design proper RESTful API.

Honza Javorek

November 20, 2013

More Decks by Honza Javorek

Other Decks in Technology


  1. REST API MANUAL Honza Javorek, 11/2013 Based on Steve Klabnik's

    great article Haters gonna HATEOAS http://timelessrepo.com/haters-gonna-hateoas
  2. Honza Javorek? 1/154

  3. honzajavorek.cz 2/154

  4. Learn how to avoid “Bro, that's not really RESTful.” 3/154

  5. REST = Representational State Transfer Fielding, Roy Thomas (2000), Architectural

    Styles and the Design of Network-based Software Architectures, Doctoral dissertation, University of California, Irvine no implementation details goals constraints → REST + HTTP REST × SOAP et al. 4/154
  6. REST constraints • client-server • stateless state of the resource

    • cacheable • layered system load balancing, cache, etc. • uniform interface guiding principles 5/154
  7. uniform interface guiding principles ? 6/154

  8. REST guiding principles • identification of resources URIs • manipulation

    of resources through these representations representation and it's metadata = enough information to manipulate it • self-descriptive messages each message = enough information to process it (MIME, cache, ...) • hypermedia as the engine of application state HATEOAS, hyperlinks, hypertext 7/154
  9. Leonard Richardson's Maturity Model http://martinfowler.com/articles/richardsonMaturityModel.html 4 steps toward the glory

    of REST 8/154
  10. 4 levels of “REST support” 1. “The Swamp of POX”

    You’re using HTTP to make RPC calls. HTTP is only really used as a tunnel. 2.Resources Rather than making every call to a service endpoint, you have multiple endpoints that are used to represent resources, and you’re talking to them. 3.HTTP verbs You interact with resources using HTTP verbs, rather than always using POST. 4.HATEOAS Hypermedia Controls. HATEOAS. You’re 100% REST compliant. 9/154
  11. HTTP REST ≠ 10/154

  12. HTTP REST ≠ 10/154

  13. HTTP REST ≠ čím víc bludišťáků, tím víc RESTful 10/154

  14. REST can be provided over any protocol. Boring fact: Everyone

    implementing REST uses HTTP. HTTP REST architecture You want your API to be here 11/154
  15. resources RPC ≠ 12/154

  16. POST /photos.getInfo POST /photos.comments.addComment POST /photos.comments.deleteComment POST /photos.comments.editComment 13/154

  17. POST /photos.getInfo POST /photos.comments.addComment POST /photos.comments.deleteComment POST /photos.comments.editComment 13/154


  19. POST /photos/add POST /comments/add POST /comments/42/delete

  20. CRUD HTTP verbs →

  21. POST /photos/add POST /photos/1/delete


  23. GET /photos/ POST /photos/ GET /photos/1 PUT /photos/1 PATCH /photos/1

    DELETE /photos/1
  24. Content negotiation

  25. GET /photos.xml GET /photos.json GET /v1/photos.json


  27. None
  28. Content negotiation as we know it Accept-Language: de; q=1.0, en;

    q=0.5 Accept: text/html; q=1.0, text/*; q=0.8, image/gif; q=0.6, image/jpeg; q=0.6, image/*; q=0.5, */*; q=0.1
  29. Content negotiation & API formats Accept: application/json {'body': {'nipples': 2,

    'legs': 2}} Accept: application/xml <?xml version="1.0" encoding="UTF-8" ?> <body> <nipples>2</nipples> <legs>2</legs> </body>
  30. Content negotiation & API versions Accept: application/json {'body': {'nipples': 2,

    'legs': 2}} Accept: application/mattel.v1+json {'body': {'nipples': 2}} http://barelyenough.org/blog/2008/05/versioning-rest-web-services/
  31. Content negotiation & language Accept-Language: en {'name': 'Barbie', 'body': ...}

    Accept-Language: cs {'name': 'Barbie', 'body': ...}
  32. Content negotiation & language Accept-Language: en {'title': 'The Good Soldier

    Švejk'} Accept-Language: cs {'title': 'Osudy dobrého vojáka Švejka za světové války'}

  34. HATEOAS • Hypertext As The Engine Of Application State •

    hypertext • engine • application state
  35. Your application is just a big state machine. se stim

  36. HATEOAS • single entry endpoint to your API • you

    can do whatever you need just by inspecting the API • transitions are made by hyperlinks – URIs • abstracting away implementation details iOS apps Sounds familiar? Yes, it's exactly how HTML and websites work.
  37. GET /author/10 { 'id': 10, 'name': 'Gargamel', } GET /author/10/posts/

    [ {'id': 3, 'title': 'How to cook smurfs', ...}, {'id': 2, 'title': 'How to chase smurfs', ...}, ] GET /author/10/comments/ [ {'id': 12293, 'text': 'I hate you.'}, {'id': 49939, 'text': 'Smurfs are idiots.'}, ]

  39. GET /author/10 { 'uri': '/author/10', 'name': 'Gargamel', 'posts': '/author/10/posts/', 'comments':

    '/author/10/comments/', } GET /author/10/posts/ [ {'uri': '/posts/3', 'title': 'How to...', ...}, {'uri': '/posts/2', 'title': 'How to...', ...}, ] GET /author/10/comments/ [ {'uri': '/comments/12293', 'text': 'I hate you.'}, {'uri': '/comments/49939', 'text': 'Smurfs...'}, ]
  40. These are nice, but... really, why should I bother?

  41. RESTful API pros & cons • Beautifully consistent and usable.

    API clients will love you. Look at Django REST framework's browsable APIs. • It is the future. (Everyone says it, so it must be true.) HTTP2.0 solves the biggest flaws. HTTP2.0 async, multiplexing, compression, pipelining, etc. → • Designed for scale. Everything is designed for massive caching and counts with presence of middleware. • Change tolerant. Change business logic in a single place! Without the links the client must implement logic for building links. If you put this code inside your iPhone or Android clients you cannot change the URI structure on the server without breaking existing clients. If a link is present the client can follow the link. A client application does not have to repeat the business logic for deciding if a book can be purchased or downloaded. • URIs are implementation detail. Choose a URI naming scheme that fits whatever framework or coding conventions that we find useful. 150/154
  42. Conclusion • stick to HTTP • ensure that everything is

    a resource • implement CRUD as HTTP verbs • use content negotiation instead of crippling your URIs • use the old mighty hypertext instead of juggling with IDs on client side 151/154
  43. Other suff – best practices • HTTP status codes •

    caching • authorization • rate limiting • OPTIONS • error handling • ... 152/154
  44. whatever you use, make your API OPINIONATED & CONSISTENT 153/154

  45. cast: