REST API MANUAL

How to design proper RESTful API.

Transcript

1. REST API MANUAL
   Honza Javorek, 11/2013
   Based on Steve Klabnik's great article Haters gonna HATEOAS
   http://timelessrepo.com/haters-gonna-hateoas
   

   View Slide

2. Honza Javorek?
   1/154
   

   View Slide

3. honzajavorek.cz
   2/154
   

   View Slide

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

   View Slide

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
   

   View Slide

6. REST constraints
   ● client-server
   ● stateless state of the resource
   ● cacheable
   ● layered system load balancing, cache, etc.
   ● uniform interface guiding principles
   5/154
   

   View Slide

7. uniform interface
   guiding principles
   ?
   6/154
   

   View Slide

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
   

   View Slide

9. Leonard Richardson's
   Maturity Model
   http://martinfowler.com/articles/richardsonMaturityModel.html
   4 steps toward the glory of REST
   8/154
   

   View Slide

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
    

    View Slide

11. HTTP REST
    ≠
    10/154
    

    View Slide

12. HTTP REST
    ≠
    10/154
    

    View Slide

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

    View Slide

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
    

    View Slide

15. resources RPC
    ≠
    12/154
    

    View Slide

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

    View Slide

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

    View Slide

18. RESOURCES,
    MOTHERFUCKER!
    

    View Slide

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

    View Slide

20. CRUD HTTP verbs
    →
    

    View Slide

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

    View Slide

22. VERBS,
    MOTHERFUCKER!
    

    View Slide

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

    View Slide

24. Content negotiation
    

    View Slide

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

    View Slide

26. HEADERS,
    MOTHERFUCKER!
    

    View Slide

27. View Slide

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
    

    View Slide

29. Content negotiation & API formats
    Accept: application/json
    {'body': {'nipples': 2, 'legs': 2}}
    Accept: application/xml
    
    
    2
    2
    
    

    View Slide

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/
    

    View Slide

31. Content negotiation & language
    Accept-Language: en
    {'name': 'Barbie', 'body': ...}
    Accept-Language: cs
    {'name': 'Barbie', 'body': ...}
    

    View Slide

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'}
    

    View Slide

33. HATEOAS
    

    View Slide

34. HATEOAS
    ● Hypertext As The Engine Of Application State
    ● hypertext
    ● engine
    ● application state
    

    View Slide

35. Your application is just a big state machine.
    se stim smiř
    

    View Slide

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.
    

    View Slide

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.'},
    ]
    

    View Slide

38. STATE
    TRANSITIONS,
    MOTHERFUCKER!
    

    View Slide

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...'},
    ]
    

    View Slide

40. These are nice, but... really, why should I bother?
    

    View Slide

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
    

    View Slide

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
    

    View Slide

43. Other suff – best practices
    ● HTTP status codes
    ● caching
    ● authorization
    ● rate limiting
    ● OPTIONS
    ● error handling
    ● ...
    152/154
    

    View Slide

44. whatever you use, make your API
    OPINIONATED & CONSISTENT
    153/154
    

    View Slide

45. cast:
    

    View Slide