Hypermedia API and how to document it effectively

Editor's Notes

• #5: This term is also coined by Ted Nelson.
• #6: Architectural Styles and the Design of Network-based Software Architectures, Fielding's doctoral dissertation, describes Representational State Transfer (REST) as a key architectural principle of the World Wide Web. The architectural abstractions and constraints Roy Fielding established led to the introduction of HATEOAS.
• #7: A distributed application makes forward progress by transitioning from one state to another, just like a state machine. The difference from traditional state machines, however, is that the possible states and the transitions between are not known in advance. Instead, as the application reaches a new state, the next possible transitions are discovered. It is like a treasure hunt. In a hypermedia system, application states are communicated through representations of uniquely identifiable resources. The identifiers of the states to which the application can transition are embedded in the representation of the current state in the form of links. This, in simple terms, is what the famous HATEOAS constraint is all about. We see it in action everyday on the Web, when we follow the links to other pages within our browser.
• #8: Resources are the fundamental building blocks of the web-based system.  A resource can be anything that we expose to the Web. It can be a document or movie clip or a product or a business process. To use a resource like interacting with it on the network or manipulating it resource needs to be identifiable which means resource should get an ID. The web provides the URI (Uniform Resource Identifier) for this purpose. A URI uniquely identifies a web resource and at the same time makes it addressable. Examples of the URIs: http://example.com/customers/45679 , http://example.com/customers/45679/orders/123 . The relationship between URIs and resources is many to one. A URI identifies only one resource, but a resource can have more than one URI just like a human can have more than one email address or telephone number. A resource must have at least one identifier to be addressable on the web, and each identifier is associated with one or more representations. A representation is a transformation or a view of a resource’s state at an instant in time. It is important to remember that a resource can have one-to-many relationship with its representations. Resources need to be linked together. Server provides a set of links to the client that enables the client to move the application from one state to the next by following a link. Links make an application dynamic. It is the core concept of hypermedia: by transiting links between resources, we change the state of an application. There is a formal description of it: Hypermedia as the engine of application state (HATEOAS). The benefit of the link approach using URIs is that the links can point to the resources that can be provided by a different application, a different server, or event a different company. The standard HTTP methods like GET, PUT, POST, DELETE need to be used correctly in order to make the clients interact with the resources. These are also called HTTP verbs. For example, GET should be used to retrieve a representation of a resource. GET is safe and idempotent which means a same request to get a representation can be issued multiple times. PUT is for updating a resource with the data or create it at this URI if it is not there already. DELETE is for deleting a resource. Both are unsafe but idempotent. POST is for creating a new resource which is neither safe nor idempotent. When a safe method is invoked, the resource state on the server remains unchanged. An idempotent method can be invoked multiple times, the end result is the same. Following the HTTP methods correctly is important because this makes our application part of the web. In REST, the server should not have to retain some sort of communication state for any of the clients it communicates with beyond a single request. It decouples the clients from the server which improves the scalability.
• #10: Here, we have a HAL document representing an order resource with the URI "/orders/523". It has "warehouse" and "invoice" links, and its own state in the form of "currency", "status", and "total" properties.
• #28: By default four snippets get produced: curl-request.adoc http-request.adoc httpie-request.adoc http-response.adoc The above test will also produced another additional snippet related to request path parameters: path-parameters.adoc
• #34: Documentation template is written using Asciidoctor. Spring Rest Docs uses Asciidoctor by default. Asciidoctor is a text processor and publishing toolchain for converting AsciiDoc (plain-text writing format) content to HTML5, DocBook 5 (or 4.5) and other formats. Asciidoctor is written in Ruby.