Your HTTP API is not RESTful

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

Transcript

1. Your HTTP API is not RESTful @jakobmattsson www.jakobm.com
5. Current status
6. RESTful API GET PUT POST DELETE Resource URLs
7. Your HTTP API is not RESTful @jakobmattsson www.jakobm.com
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?
15. Welcome to the Internet I will be your guide
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.”
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.
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"
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 www.jakobm.com