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 full-size slide

  2. Current status

    View full-size slide

  3. RESTful API
    GET PUT POST DELETE
    Resource URLs

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  8. What is… the Internet?

    View full-size slide

  9. What is… the Internet?

    View full-size slide

  10. Welcome to the Internet
    I will be your guide

    View full-size slide

  11. The world wide web is
    HTML over HTTP

    View full-size slide

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

    View full-size slide

  13. ”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 full-size slide

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

    View full-size slide

  15. So… REST over HTTP?

    View full-size slide

  16. 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 full-size slide

  17. HyperLinks leads to…
    !
    HATEOAS

    View full-size slide

  18. Hypermedia as the Engine of
    Application State

    View full-size slide

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

    View full-size slide

  20. 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 full-size slide

  21. 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 full-size slide

  22. link: "/projects/99"

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  28. 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 full-size slide

  29. 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 full-size slide

  30. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide