Your HTTP API is not RESTful

Your HTTP API is not RESTful

Talk given at Nordic APIs Summit 2014:


Jakob Mattsson

October 21, 2014


  1. Your HTTP API is not RESTful @jakobmattsson

  2. None
  3. None
  4. None
  5. Current status


  7. Your HTTP API is not RESTful @jakobmattsson

  8. None
  9. ”I am getting frustrated by the number of people calling

    any HTTP-based interface a REST API.” ! ”That is RPC.” - me
  10. - Roy Fielding ”I am getting frustrated by the number

    of people calling any HTTP-based interface a REST API.” ! ”That is RPC.”
  11. REST? Representational state transfer is an abstraction of the architecture

    of the World Wide Web. WWW is an ”instance” of REST.
  12. What is… the Internet?

  13. What is… the Internet?

  14. None
  15. Welcome to the Internet I will be your guide

  16. None
  17. The world wide web is HTML over HTTP

  18. The world wide web is HTML over HTTP HyperText Markup

    Language over HyperText Transfer Protocol
  19. ”Hypertext is text with references (hyperlinks) to other text which

    the reader can immediately access, or where text can be revealed progressively at multiple levels of detail.”
  20. None
  21. None
  22. Hypertext does not need to be HTML on a browser.

    ! Machines can follow links when they understand the data format and relationship types.
  23. So… REST over HTTP?

  24. An Internet media type for the data (JSON, XML, HTML,

    images, video etc). ! Standard HTTP methods (GET, PUT, POST, or DELETE), with the corresponding semantics. ! Hypertext links to reference state. ! Hypertext links to reference related resources.
  25. None
  26. HyperLinks leads to… ! HATEOAS

  27. Hypermedia as the Engine of Application State

  28. A constraint of the REST application architecture that distinguishes it

    from most other network application architectures Hypermedia as the Engine of Application State
  29. A client interacts with a network application entirely through hypermedia

    provided dynamically by application servers. ! A client needs no prior knowledge about how to interact with any particular application or server beyond a generic understanding of hypermedia.
  30. By contrast, in a service-oriented architecture (SOA), clients and servers

    interact through a fixed interface shared through documentation or an interface description language (IDL).
  31. link: "/projects/99"

  32. None
  33. When your API feels like using the web itself… !

    THEN you’re starting to become RESTful.
  34. • No fixed resource names • No fixed hierarchies •

    Servers own the namespace • Servers instruct clients (links, forms etc) 1. No fixation
  35. • No types of significance for the client • Use

    media types • Use standardized relation names 2. No types
  36. • One entry point • State driven by client selections

    • Server provides options 3. No prior knowledge
  37. The HATEOAS constraint decouples client and server in a way

    that allows the server functionality to evolve independently.
  38. Changes in who can access what. ! Or what state

    transitions are valid. ! ! ! ! ! ! ! ! ! All mistakes related to WHAT url you can request WHEN, they go away.
  39. What does this look like in JSON? ! Let’s actually

    browse the API. ! Start from a native format, with various templates for other media types.
  40. DEMO

  41. Most people make the mistake that it should be simple

    to design simple things. ! In reality, the effort required to design something is inversely proportional to the simplicity of the result.
  42. Frameworks ! Rails? ASP.NET MVC? Django? Play? Spring? Express?

  43. Usually very RPC-like. ! Hope to see some alternatives in

    the future.
  44. Your HTTP API is not RESTful @jakobmattsson