Representational State Transfer - JWorks 2018

Slide 1

Slide 1 text

REST Representational State Transfer A n d r e a s E ve r s

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

REST Who builds, or has built RESTful services?

Slide 4

Slide 4 text

REST

Slide 5

Slide 5 text

REST

Slide 6

Slide 6 text

REST Identifiers

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

REST Representations

Slide 10

Slide 10 text

REST Representations Content Negotiation

Slide 11

Slide 11 text

REST Actions, for instance supplied by HTTP: GET, PUT, POST, DELETE 200, 201, 404, 500, 503, … Manipulation

Slide 12

Slide 12 text

REST

Slide 13

Slide 13 text

REST Technology Support Scalability and Performance Loose Coupling Business Processes Consistency and Uniformity The Web as Application Platform

Slide 14

Slide 14 text

REST

Slide 15

Slide 15 text

REST

Slide 16

Slide 16 text

REST

Slide 17

Slide 17 text

REST

Slide 18

Slide 18 text

REST

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

REST The Uniform Interface Interface constraints Identification of resources Manipulation of resources through representations Self-descriptive messages Hypermedia as the engine of application state

Slide 21

Slide 21 text

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.

Slide 22

Slide 22 text

REST Richardson’s Maturity Model

Slide 23

Slide 23 text

REST The Swamp of POX

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

REST URI Tunneling

Slide 26

Slide 26 text

REST URI Tunneling Only one verb (typically GET) Many URIs Operation names and parameters are passed in the URI

Slide 27

Slide 27 text

REST URI Tunneling

Slide 28

Slide 28 text

REST CRUD Services

Slide 29

Slide 29 text

REST CRUD Services HTTP verbs and response codes are used E.g. https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html

Slide 30

Slide 30 text

REST The Glory of REST

Slide 31

Slide 31 text

REST The Glory of REST Hypermedia As The Engine Of Application State Representations contain links to other resources

Slide 32

Slide 32 text

REST Practical Implementation R E ST

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

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

Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

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

Slide 37

Slide 37 text

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

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

REST PATCH Used to partially update existing single resources »please change the resource identified by the URI according to my change request« HTTP

Slide 40

Slide 40 text

REST PATCH JSON Merge Patch { "a": "b", "c": { "d": "e", "f": "g" } } HTTP { "a": "z", "c": { "f": "null" } } { "a": "z", "c": { "d": "e" } }

Slide 41

Slide 41 text

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" } }

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

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

Slide 45

Slide 45 text

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

Slide 46

Slide 46 text

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

Slide 47

Slide 47 text

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

Slide 48

Slide 48 text

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

Slide 49

Slide 49 text

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

Slide 50

Slide 50 text

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

Slide 51

Slide 51 text

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

Slide 52

Slide 52 text

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

Slide 53

Slide 53 text

REST Headers Location Prefer ETag & If-(None-)Match If-(Un)Modified-Since Accept & Content-Type Cache-Control & Vary HTTP

Slide 54

Slide 54 text

REST Avoid Versioning Versioning adds complexity to your system Versioning

Slide 55

Slide 55 text

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

Slide 56

Slide 56 text

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

Slide 57

Slide 57 text

REST Media Type Versioning /v1/companies/123/employees /companies/123/employees/v1 application/vnd.acme.employees.v1+json Versioning

Slide 58

Slide 58 text

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

Slide 59

Slide 59 text

REST Filtering GET http://myapi/resources/123 { "name": "John Doe", "birthday": "1984-09-13", "partner": { "name": "Jane Doe", "birthday": "1988-04-07" } } Performance

Slide 60

Slide 60 text

REST Filtering GET http://myapi/resources/123?fields=(name,partner(name)) { "name": "John Doe", "partner": { "name": "Jane Doe" } } Performance

Slide 61

Slide 61 text

REST Embedding GET http://myapi/order/123 { "id": "123", "orderTime": "2015-05-28T14:07:17Z", } Performance

Slide 62

Slide 62 text

REST Embedding GET http://myapi/order/123?embed=(items) { "id": "123", "orderTime": "2015-05-28T14:07:17Z", "_embedded": { "items": […] } } Performance

Slide 63

Slide 63 text

REST Pagination Cursor-based: GET http://myapi/resources?count=5 &cursor=1374004777531007833 { "ids": [ 333156387, 333155835, ... 101141469, 92896225 ], "next_cursor": 1323935095007282836, "previous_cursor": -1374003371900410561 } Performance

Slide 64

Slide 64 text

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

Slide 65

Slide 65 text

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

Slide 66

Slide 66 text

REST Fire and forget with polling 202 Accepted status code Location header for polling Asynchronicity

Slide 67

Slide 67 text

REST WADL Schemas

Slide 68

Slide 68 text

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

Slide 69

Slide 69 text

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

Slide 70

Slide 70 text

REST Slate Schemas

Slide 71

Slide 71 text

REST Slate Similar to WADL, but smaller userbase and relatively untested Schemas

Slide 72

Slide 72 text

REST OpenAPI (Swagger) Schemas

Slide 73

Slide 73 text

REST OpenAPI (Swagger) High adoption, but serious hidden flaws (leaky, intrusive, heavy, discourages tolerant reader) Schemas

Slide 74

Slide 74 text

REST RAML Schemas

Slide 75

Slide 75 text

REST RAML Supports advanced constructs, decent adoption, human readable format, high industry backing Lacks code-level tooling, still unproven long-term Schemas

Slide 76

Slide 76 text

REST API Blueprint Schemas

Slide 77

Slide 77 text

REST API Blueprint Easy to understand, simple to write Low adoption, lacks advanced constructs in general, complex installation Schemas

Slide 78

Slide 78 text

REST Consumer Driven Contracts Schemas

Slide 79

Slide 79 text

REST Returns 10 properties Uses property 1-2

Slide 80

Slide 80 text

REST Uses property 1-2 Uses property 3-4 Uses property 3-5 Uses property 4-5 Returns 10 properties

Slide 81

Slide 81 text

REST Returns 10 properties Uses property 1-2 Consumer 1 uses property 1-2 PR

Slide 82

Slide 82 text

REST Returns 10 properties Uses property 1-2

Slide 83

Slide 83 text

REST Consumer Driven Contracts Pact or Spring Cloud Contract In conjunction with REST Docs Schemas

Slide 84

Slide 84 text

REST

Slide 85

Slide 85 text

REST Hypermedia Hypermedia As The Engine Of Application State

Slide 86

Slide 86 text

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

Slide 87

Slide 87 text

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

Slide 88

Slide 88 text

REST Concretely?

Slide 89

Slide 89 text

REST Hateaos In Action

Slide 90

Slide 90 text

REST

Slide 91

Slide 91 text

REST

Slide 92

Slide 92 text

REST

Slide 93

Slide 93 text

REST

Slide 94

Slide 94 text

REST

Slide 95

Slide 95 text

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

Slide 96

Slide 96 text

REST Hateoas In Action HTML is a hypermedia format is a link with method GET 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

Slide 97

Slide 97 text

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”

Slide 98

Slide 98 text

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?

Slide 99

Slide 99 text

REST GET /account/12345 HTTP/1.1 HTTP/1.1 200 OK 12345 100.00 Hateoas Benefit: Runtime action discovery

Slide 100

Slide 100 text

REST GET /account/12345 HTTP/1.1 HTTP/1.1 200 OK 12345 -25.00 Hateoas Benefit: Runtime action discovery

Slide 101

Slide 101 text

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

Slide 102

Slide 102 text

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”

Slide 103

Slide 103 text

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

Slide 104

Slide 104 text

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

Slide 105

Slide 105 text

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

Slide 106

Slide 106 text

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