Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Your HTTP API is not RESTful

Your HTTP API is not RESTful

Talk given at Nordic APIs Summit 2014: http://lanyrd.com/2014/nordicapis

Jakob Mattsson

October 21, 2014
Tweet

More Decks by Jakob Mattsson

Other Decks in Programming

Transcript

  1. Your HTTP API
    is not RESTful
    @jakobmattsson www.jakobm.com

    View Slide

  2. View Slide

  3. View Slide

  4. View Slide

  5. Current status

    View Slide

  6. RESTful API
    GET PUT POST DELETE
    Resource URLs

    View Slide

  7. Your HTTP API
    is not RESTful
    @jakobmattsson www.jakobm.com

    View Slide

  8. View Slide

  9. ”I am getting frustrated by the
    number of people calling any
    HTTP-based interface a REST API.”
    !
    ”That is RPC.”
    - me

    View Slide

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

    View Slide

  11. REST?
    Representational state transfer is
    an abstraction of the architecture of
    the World Wide Web.
    WWW is an ”instance” of REST.

    View Slide

  12. What is… the Internet?

    View Slide

  13. What is… the Internet?

    View Slide

  14. View Slide

  15. Welcome to the Internet
    I will be your guide

    View Slide

  16. View Slide

  17. The world wide web is
    HTML over HTTP

    View Slide

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

    View Slide

  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.”

    View Slide

  20. View Slide

  21. View Slide

  22. Hypertext does not need to be HTML on
    a browser.
    !
    Machines can follow links when they
    understand the data format and
    relationship types.

    View Slide

  23. So… REST over HTTP?

    View Slide

  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.

    View Slide

  25. View Slide

  26. HyperLinks leads to…
    !
    HATEOAS

    View Slide

  27. Hypermedia as the Engine of
    Application State

    View Slide

  28. A constraint of the REST
    application architecture that
    distinguishes it from most other
    network application architectures
    Hypermedia as the Engine of
    Application State

    View Slide

  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.

    View Slide

  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).

    View Slide

  31. link: "/projects/99"

    View Slide

  32. View Slide

  33. When your API feels like
    using the web itself…
    !
    THEN you’re starting to
    become RESTful.

    View Slide

  34. • No fixed resource names
    • No fixed hierarchies
    • Servers own the namespace
    • Servers instruct clients (links, forms etc)
    1. No fixation

    View Slide

  35. • No types of significance for the client
    • Use media types
    • Use standardized relation names
    2. No types

    View Slide

  36. • One entry point
    • State driven by client selections
    • Server provides options
    3. No prior knowledge

    View Slide

  37. The HATEOAS constraint decouples
    client and server in a way that allows
    the server functionality to evolve
    independently.

    View Slide

  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.

    View Slide

  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.

    View Slide

  40. DEMO

    View Slide

  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.

    View Slide

  42. Frameworks
    !
    Rails? ASP.NET MVC? Django?
    Play? Spring? Express?

    View Slide

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

    View Slide

  44. Your HTTP API
    is not RESTful
    @jakobmattsson www.jakobm.com

    View Slide