Representational State Transfer - JWorks 2018

Training on the best practices of REST APIs by Andreas Evers

Transcript

1. REST Representational State Transfer A n d r e a s E ve r s
2. REST The Web, as we currently know it, isn’t the be-all and end-all of computing, but many people believe it offers an important lesson on how to construct systems of networked components. Many people take advantage of its protocol, HTTP, to connect systems. But some people think we should go further, using HTTP not as a convenient tunnel, but to embrace the way the Web works as a foundation for systems collaboration. The World Wide Web Martin Fowler
3. REST Who builds, or has built RESTful services?
4. REST
5. REST
6. REST Identifiers
7. REST Term Comments URI (Uniform Resource Identifier) Not “Universal” or “Unique” Resource Identifier; only “Uniform” is correct. IRI (International Resource Identifier) An update to the definition of URI to allow the use of international characters. URN (Uniform Resource Name) URI with “urn” as the scheme, used to convey unique names in a particular “namespace.” The namespace is defined as part of the URN’s structure. E.g. urn:isbn:0131401602. URL (Uniform Resource Locator) URI which includes the “access mechanism” or “network location” Address Many think of resources as having “addresses” on the Web and, as a result, refer to their identifiers as such. Identifiers
8. REST Identifiers URI & URL URI & URL URI & URL INI & URL URI & URL URI & URL URI & URL URI URI & URL URI URI ftp://ftp.is.co.za/rfc/rfc1808.txt http://www.ietf.org/rfc/rfc2396.txt ldap://[2001:db8::7]/c=GB?objectClass?one https://en.wiktionary.org/wiki/Ῥόδος https://en.wiktionary.org/wiki/%E1%BF%AC%CF%8C%CE%B 4%CE%BF%CF%82 mailto:John.Doe@example.com news:comp.infosystems.www.servers.unix tel:+1-816-555-1212 telnet://192.0.2.16:80/ urn:oasis:names:specification:docbook:dtd:xml:4.1.2 urn:isbn:0131401602
9. REST Representations
10. REST Representations Content Negotiation
11. REST Actions, for instance supplied by HTTP: GET, PUT, POST, DELETE 200, 201, 404, 500, 503, … Manipulation
12. REST
13. REST Technology Support Scalability and Performance Loose Coupling Business Processes Consistency and Uniformity The Web as Application Platform
14. REST
15. REST
16. REST
17. REST
18. REST
19. REST The Uniform Interface The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components. Roy Fielding
20. REST The Uniform Interface Interface constraints Identification of resources Manipulation of resources through representations Self-descriptive messages Hypermedia as the engine of application state
21. REST Resources Consider the domain entities that take part in web service interaction, and aim to model your API around these using the standard HTTP methods as operation indicators. For instance, if an application has to lock articles explicitly so that only one user may edit them, create an article lock with PUT or POST instead of using a lock action.
22. REST Richardson’s Maturity Model
23. REST The Swamp of POX
24. REST The Swamp of POX Full-blown services which use only: A single URL A single verb (mostly POST) Examples: WS-*: POST http://myapi/ws GraphQL : POST http://myapi/graphql
25. REST URI Tunneling
26. REST URI Tunneling Only one verb (typically GET) Many URIs Operation names and parameters are passed in the URI
27. REST URI Tunneling
28. REST CRUD Services
29. REST CRUD Services HTTP verbs and response codes are used E.g. https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html
30. REST The Glory of REST
31. REST The Glory of REST Hypermedia As The Engine Of Application State Representations contain links to other resources
32. REST Practical Implementation R E ST
33. REST Pluralize resource names (hacking up the tree) /customers/131/products/32/details /customers/131/products/32 /customers/131/products /customers/131 /customers Avoid /api prefix if unnecessary Avoid file extensions (use content negotiation) Avoid trailing slashes API Naming
34. REST Never use actions or verbs in resource names POST /bookings/123/cancel POST /bookings/123/cancellation GET /createAccount POST /accounts GET /createAccount POST /accounts Define useful resources Resources should be defined to cover 90% of all its client’s use cases & contain as much information as necessary, but as little as possible The final 10% should be supported with filtering or embedding details Resource Naming
35. REST GET NO request body payload GET with Body Either GET with URL encoded query parameters Or POST with body content (depends on size limits of clients, gateways, and servers) HTTP
36. REST PUT Used to create or update entire resources - single or collection resources »please put the enclosed representation at the resource mentioned by the URI, replacing any existing resource« HTTP
37. REST PUT Requires the entire resource to be provided in the request body Concurrent PUTs might create conflicts, use ETags with If-(None-)Match HTTP
38. REST POST Used for scenarios not covered by other verbs Should not be used on single resources (undefined semantic) »please add the enclosed representation to the collection resource identified by the URI« HTTP
39. REST PATCH Used to partially update existing single resources »please change the resource identified by the URI according to my change request« HTTP
40. REST PATCH JSON Merge Patch { "a": "b", "c": { "d": "e", "f": "g" } } HTTP { "a": "z", "c": { "f": "null" } } { "a": "z", "c": { "d": "e" } }
41. REST PATCH JSON Patch { "a": "b", "c": { "d": "e", "f": "g" } } HTTP [ { "op": "replace", "path": "/a", "value": "z" }, { "op": "remove", "path": "/c/d" } ] { "a": "z", "c": { "d": "e" } }
42. REST PATCH 1. Use PUT with complete resource if feasible 2. Use JSON Merge Patch (application/merge-patch+json) 3. Use JSON Patch (application/json-patch+json) 4. Use POST if the request does not modify the resource in a way defined by the semantics of the media type HTTP Concurrent PATCHs might create conflicts, use ETags with If-(None-)Match
43. REST DELETE Used to delete a resource Note: a successful server response is an intention of the server to either delete or move the resource to an inaccessible location HTTP
44. REST HEAD Used to retrieve the header information of single resources and resource collections Exactly the same as GET, but without the response body HTTP
45. REST OPTIONS Used to inspect the available operations (HTTP methods) of a given endpoint Uses the Allow headers in the response Rarely implemented, except for CORS preflight request support HTTP
46. REST Safeness & idempotency HTTP HTTP method safe idempotent OPTIONS Yes Yes HEAD Yes Yes GET Yes Yes PUT No Yes POST No No DELETE No Yes PATCH No No
47. REST Statuscodes - Success HTTP Code Meaning Methods 200 OK - this is the standard success response All 201 Created - Returned on successful entity creation. You are free to return either an empty response or the created resource in conjunction with the Location header. Always set the Location header. POST, PUT 202 Accepted - The request was successful and will be processed asynchronously. POST, PUT, DELETE, PATCH 204 No content - There is no response body PUT, DELETE, PATCH 207 Multi-Status - The response body contains multiple status informations for different parts of a batch/bulk request. POST
48. REST Statuscodes - Redirection HTTP Code Meaning Methods 301 Moved Permanently - This and all future requests should be directed to the given URI. All 303 See Other - The response to the request can be found under another URI using a GET method. PATCH, POST, PUT, DELETE 304 Not Modified - resource has not been modified since the date or version passed via request headers If-Modified-Since or If-None-Match. GET
49. REST Statuscodes - Client Side Errors HTTP Code Meaning Methods 400 Bad request - generic / unknown error All 401 Unauthorized - the users must log in (this often means “Unauthenticated”) All 403 Forbidden - the user is not authorized to use this resource All 404 Not found - the resource is not found All 405 Method Not Allowed - the method is not supported, see OPTIONS All 406 Not Acceptable - resource can only generate content not acceptable according to the Accept headers sent in the request All 408 Request timeout - the server times out waiting for the resource All
50. REST Statuscodes - Client Side Errors HTTP Code Meaning Methods 409 Conflict - request cannot be completed due to conflict, e.g. when two clients try to create the same resource or if there are concurrent, conflicting updates POST, PUT, DELETE, PATCH 410 Gone - resource does not exist any longer, e.g. when accessing a resource that has intentionally been deleted All 412 Precondition Failed - returned for conditional requests, e.g. If-Match if the condition failed. Used for optimistic locking. PUT, DELETE, PATCH 415 Unsupported Media Type - e.g. clients sends request body without content type POST, PUT, DELETE, PATCH 423 Locked - Pessimistic locking, e.g. processing states PUT, DELETE, PATCH
51. REST Statuscodes - Client Side Errors HTTP Code Meaning Methods 428 Precondition Required - server requires the request to be conditional (e.g. to make sure that the “lost update problem” is avoided). All 429 Too many requests - the client does not consider rate limiting and sent too many requests. All
52. REST Statuscodes - Server Side Errors HTTP Code Meaning Methods 500 Internal Server Error - a generic error indication for an unexpected server execution problem (here, client retry may be sensible) All 501 Not Implemented - server cannot fulfill the request (usually implies future availability, e.g. new feature). All 503 Service Unavailable - server is (temporarily) not available (e.g. due to overload) — client retry may be sensible. All
53. REST Headers Location Prefer ETag & If-(None-)Match If-(Un)Modified-Since Accept & Content-Type Cache-Control & Vary HTTP
54. REST Avoid Versioning Versioning adds complexity to your system Versioning
55. REST Backwards Compatibility Through Compatible extensions Versioning Producers: Add only optional fields Never change semantics of fields Never change validation logic to be more restrictive Enum ranges for output can be reduced but not extended Enum ranges for input can be reduced (while mapping old values), and extended Support redirection in case URIs change Consumers: Be tolerant for unknown fields Be prepared to handle unexpected status codes Follow redirects
56. REST Forwards Compatibility? Producers could be running an older version of the API than their consumers due to rollback or phased rollout Robustness principle dictates: ignore unknown request fields BUT: impossible for PUT (asymmetric with subsequent GET) client errors might be ignored clients might conflict with already used but ignored fields Versioning
57. REST Media Type Versioning /v1/companies/123/employees /companies/123/employees/v1 application/vnd.acme.employees.v1+json Versioning
58. REST Deprecation Obtain approval of all clients Make sure external partners agree on deprecation timespan Reflect deprecation in the API definition Monitor the usage of deprecated APIs Add a warning to deprecated API responses (Warning header) Clients should monitor the Warning header Versioning
59. REST Filtering GET http://myapi/resources/123 { "name": "John Doe", "birthday": "1984-09-13", "partner": { "name": "Jane Doe", "birthday": "1988-04-07" } } Performance
60. REST Filtering GET http://myapi/resources/123?fields=(name,partner(name)) { "name": "John Doe", "partner": { "name": "Jane Doe" } } Performance
61. REST Embedding GET http://myapi/order/123 { "id": "123", "orderTime": "2015-05-28T14:07:17Z", } Performance
62. REST Embedding GET http://myapi/order/123?embed=(items) { "id": "123", "orderTime": "2015-05-28T14:07:17Z", "_embedded": { "items": […] } } Performance
63. REST Pagination Cursor-based: GET http://myapi/resources?count=5 &cursor=1374004777531007833 { "ids": [ 333156387, 333155835, ... 101141469, 92896225 ], "next_cursor": 1323935095007282836, "previous_cursor": -1374003371900410561 } Performance
64. REST Pagination Offset/Limit-based: GET http://myapi/resources?limit=5&start=5 { "ids": [ 333156387, 333155835, 101141469, 92896225 ], "size": 4, "start": 5, "limit": 5 } Performance
65. REST Pagination Performance Cursor-based Offset/Limit-based Much better performance (NoSQL) Next-previous more popular than specific pages Support for adding or deleting entries except the cursor itself Much better tooling support Supports jumping to specific page Supports backward iteration Supports total count
66. REST Fire and forget with polling 202 Accepted status code Location header for polling Asynchronicity
67. REST WADL Schemas
68. REST WADL WADL can be used to automatically generate plumbing code with very little effort, compared to manually building clients. Since the client and server collaborate over the life cycle of a resource, its URI, and its representation format, it does not matter whether the plumbing is generated from a metadata description. Indeed, WADL descriptions may help expedite consumer-side maintenance when changes happen on the server side. Schemas
69. REST WADL The Web uses hypermedia to provide contracts in a much more loosely coupled way than WADL. But for CRUD-only services, WADL can be a useful tool, although very time-consuming to create. Schemas
70. REST Slate Schemas
71. REST Slate Similar to WADL, but smaller userbase and relatively untested Schemas
72. REST OpenAPI (Swagger) Schemas
73. REST OpenAPI (Swagger) High adoption, but serious hidden flaws (leaky, intrusive, heavy, discourages tolerant reader) Schemas
74. REST RAML Schemas
75. REST RAML Supports advanced constructs, decent adoption, human readable format, high industry backing Lacks code-level tooling, still unproven long-term Schemas
76. REST API Blueprint Schemas
77. REST API Blueprint Easy to understand, simple to write Low adoption, lacks advanced constructs in general, complex installation Schemas
78. REST Consumer Driven Contracts Schemas
79. REST Returns 10 properties Uses property 1-2
80. REST Uses property 1-2 Uses property 3-4 Uses property 3-5 Uses property 4-5 Returns 10 properties
81. REST Returns 10 properties Uses property 1-2 Consumer 1 uses property 1-2 PR
82. REST Returns 10 properties Uses property 1-2
83. REST Consumer Driven Contracts Pact or Spring Cloud Contract In conjunction with REST Docs Schemas
84. REST
85. REST Hypermedia Hypermedia As The Engine Of Application State
86. REST https://vimeo.com/20781278 Sub-constraints: • Identification of resources (URIs) • Manipulation via representations (request & response bodies) • Self-descriptive messages (headers) • Hypermedia as the engine of application state HTTP as application protocol
87. REST Sub-constraints: • Identification of resources (URIs) • Manipulation via representations (request & response bodies) • Self-descriptive messages (headers) • Hypermedia as the engine of application state https://vimeo.com/20781278 If you don’t do this Then you don’t adhere to this And you are missing out on these
88. REST Concretely?
89. REST Hateaos In Action
90. REST
91. REST
92. REST
93. REST
94. REST
95. REST Hateoas In Action How would you explain to a client to get to the Nerd in the Basement painting? Go to Amazon.com, in the categories go to fine arts, follow paintings, more specifically oil paintings, and click on the one with the title Nerd in the Basement Type http://www.amazon.com/Nerd-in-the- Basement/dp/B00L849CSS/ref=lp_6685279011_1_2?s=art&ie=UTF8&qi d=1431864368&sr=1-2 in your browser
96. REST Hateoas In Action HTML is a hypermedia format <a> is a link with method GET <form> is a link with method POST (or other if specified) The browser understands this syntax and shows a link or a form if the server response contains these tags
97. REST Hateoas Requirements Communication between Client and Server depends on: • Where does the client have to start? Root API In regular websites: the homepage • Where am I? How do I interpret the current API response? In regular websites: the syntax of HTML is interpreted by the browser • Where can I go? What does a link or form with a certain relation or class mean? In regular websites: link with relation “stylesheet”, form with action “login”
98. REST Hateoas In Action Amazon.com (and any other website in the whole world wide web) applies Hateoas. Why wouldn’t your API do the same?
99. REST GET /account/12345 HTTP/1.1 HTTP/1.1 200 OK <?xml version="1.0"?> <account> <account_number>12345</account_number> <balance currency="usd">100.00</balance> <link rel="deposit" href="/account/12345/deposit" /> <link rel="withdraw" href="/account/12345/withdraw" /> <link rel="transfer" href="/account/12345/transfer" /> <link rel="close" href="/account/12345/close" /> </account> Hateoas Benefit: Runtime action discovery
100. REST GET /account/12345 HTTP/1.1 HTTP/1.1 200 OK <?xml version="1.0"?> <account> <account_number>12345</account_number> <balance currency="usd">-25.00</balance> <link rel="deposit" href="/account/12345/deposit" /> </account> Hateoas Benefit: Runtime action discovery
101. REST Hateoas Concern: Scope In case of one or two clients built in the same team, it is arguable whether auto-discoverability is really a necessity
102. REST Hateoas Benefit: Non-structural Changes “categories/1/oil-paintings/1234” auto-discoverable through HATEOAS as “categories[1].oil-paintings[1234]” will not break when 1234 as id is changed to “basementNerd”
103. REST Hateoas Benefit: Changing the URI of a Resource “categories/1/oil-paintings/1234” being returned as part as the response body of “categories/1” will not break the client
104. REST Content Types JSON NOT hypermedia-aware by default Needs a fixed format to support links and forms Many formats available XHTML IS hypermedia-aware by default Harder to process XHTML responses using javascript (xpath is required) The API responses can also be read by a human as regular HTML pages SVG, Atom, HTML Similar as XHTML but not preferred
105. REST JSON Formats JSON-LD Augmenting existing APIs without introducing breaking changes Needs HYDRA as a vocabulary for communicating operations Decoupling of API serialization format & communication format HAL Minimal, light weight syntax and semantics Offers most of the benefits of using a hypermedia type Easy to convert existing API to HATEOAS Chosen and supported by Spring No support for specifying operations
106. REST JSON Formats Collection+JSON Can list queries that your collection supports and templates that clients can use to alter your collection Great for publishing user editable data SIREN Represents generic classes of items Supports operations Concept of classes, bringing a sense of type information to your API responses
107. REST Considerations Maturity Client implementation Caching Versioning
108. REST
109. REST https://zalando.github.io/restful-api-guidelines
110. REST
111. REST Who builds, or has built RESTful services?
112. REST Representational State Transfer A n d r e a s E ve r s