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
“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
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
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.
/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
Should not be used on single resources (undefined semantic) »please add the enclosed representation to the collection resource identified by the URI« HTTP
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
- 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
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
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
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
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
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
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
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
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
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
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
via representations (request & response bodies) • Self-descriptive messages (headers) • Hypermedia as the engine of application state HTTP as application protocol
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
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
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
• 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”
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
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
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