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

Representational State Transfer - JWorks 2018

Representational State Transfer - JWorks 2018

Training on the best practices of REST APIs by Andreas Evers

Andreas Evers

May 07, 2018
Tweet

More Decks by Andreas Evers

Other Decks in Technology

Transcript

  1. 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
  2. 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
  3. 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:[email protected] 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
  4. REST Actions, for instance supplied by HTTP: GET, PUT, POST,

    DELETE 200, 201, 404, 500, 503, … Manipulation
  5. REST Technology Support Scalability and Performance Loose Coupling Business Processes

    Consistency and Uniformity The Web as Application Platform
  6. 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
  7. REST The Uniform Interface Interface constraints Identification of resources Manipulation

    of resources through representations Self-descriptive messages Hypermedia as the engine of application state
  8. 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.
  9. 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
  10. REST URI Tunneling Only one verb (typically GET) Many URIs

    Operation names and parameters are passed in the URI
  11. REST CRUD Services HTTP verbs and response codes are used

    E.g. https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html
  12. REST The Glory of REST Hypermedia As The Engine Of

    Application State Representations contain links to other resources
  13. 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
  14. 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
  15. 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
  16. 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
  17. 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
  18. 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
  19. REST PATCH Used to partially update existing single resources »please

    change the resource identified by the URI according to my change request« HTTP
  20. REST PATCH JSON Merge Patch { "a": "b", "c": {

    "d": "e", "f": "g" } } HTTP { "a": "z", "c": { "f": "null" } } { "a": "z", "c": { "d": "e" } }
  21. 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" } }
  22. 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
  23. 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
  24. 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
  25. 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
  26. 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
  27. 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
  28. 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
  29. 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
  30. 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
  31. 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
  32. 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
  33. 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
  34. 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
  35. 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
  36. REST Filtering GET http://myapi/resources/123 { "name": "John Doe", "birthday": "1984-09-13",

    "partner": { "name": "Jane Doe", "birthday": "1988-04-07" } } Performance
  37. REST Pagination Cursor-based: GET http://myapi/resources?count=5 &cursor=1374004777531007833 { "ids": [ 333156387,

    333155835, ... 101141469, 92896225 ], "next_cursor": 1323935095007282836, "previous_cursor": -1374003371900410561 } Performance
  38. 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
  39. REST Fire and forget with polling 202 Accepted status code

    Location header for polling Asynchronicity
  40. 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
  41. 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
  42. REST OpenAPI (Swagger) High adoption, but serious hidden flaws (leaky,

    intrusive, heavy, discourages tolerant reader) Schemas
  43. REST RAML Supports advanced constructs, decent adoption, human readable format,

    high industry backing Lacks code-level tooling, still unproven long-term Schemas
  44. REST API Blueprint Easy to understand, simple to write Low

    adoption, lacks advanced constructs in general, complex installation Schemas
  45. REST Uses property 1-2 Uses property 3-4 Uses property 3-5

    Uses property 4-5 Returns 10 properties
  46. 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
  47. 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
  48. 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
  49. 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
  50. 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”
  51. 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?
  52. 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
  53. 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
  54. 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
  55. 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”
  56. 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
  57. 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
  58. 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
  59. 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