The document discusses the Richardson Maturity Model, outlining four levels of REST API maturity from basic SOAP-based services to fully RESTful APIs where Hypermedia as the Engine of Application State (HATEOAS) is utilized. It explains each level's characteristics, emphasizing the importance of resource-based URIs, HTTP methods, and how HATEOAS allows dynamic discovery of resources without hard-coded URIs. The document also references RFC 5988 and JSON Hypermedia API Language (HAL) as frameworks for expressing hypermedia links in REST APIs.

1. HATEOAS
Richardson Maturity Model

2. What is REST
 Before we jump into HATEOAS directly, lets look a little behind and
see how the evolution of REST happend so far.

3. Level 0 - The Swamp of POX
 API designed at this level are not at all Rest APIs and This is
where SOAP based web services takes place.
 At this Level,There is no concept of Resource Based URI,
Hypermedia, and no proper use of HTTP Protocol (which are
key characteristics of a REST API). In fact, the API, which
belongs to this Level, does not make use or leverages the full
potential of the HTTP protocol. HTTP is merely treated as a
Transport Layer protocol or just a Tunneling Mechanism
between Client and Server.

4. LEVEL 1: Resource BASED URI
 This is a starting Level for a REST API. In this Level, the Concept of
Resource-based Address is introduced, which tells you there should be
Individual URI for each Resource on the server
 It’s like reducing the burden from the single endpoint into multiple Resource
Based URIs like Divide and Conquer algorithm.

5. Level 2 - HTTP Verbs
 REST API developed at this LEVEL uses Standard HTTP methods/verbs and
different HTTP status codes to do different operations on Resource URI. So, the
Request Body will no longer carry Operation information at this level

6. LEVEL 3: Use Hypermedia or HATEOAS
 In LEVEL 1, the Resource-Based URI concept is introduced and in LEVEL 2, we leveraged the
full potential of HTTP protocol using HTTP methods. LEVEL 3 makes use of Hypermedia (also
Called HATEOAS–Hypermedia as Engine of Application state in REST world), which drives the
interaction for the API Client. Generally, the API Client is not aware of all resource endpoints and
REST does not deal much with API documents (which can tell API client information about all
endpoints), unlike SOAP where we have WSDL, which provides information about service to the
API Client.
 Different Resource Based Endpoints are made aware to API Client using concept HATEOAS i.e.
sending some hypermedia as the response of endpoint response which in turns acts as Engine
of Application state and hence the name HATEOAS. The HATEOAS concept in REST API
makes API self-documented and hence no need for API documentation.
 API developed at this LEVEL 3 is generally considered as fully RESTful API and this is where
we see the charm of REST API.

7. HATEOAS Implementation
 In the real world, when you visit a website – you hit its homepage. It presents
some snapshots and links to other sections of websites. You click on them,
and then you get more information along with more related links that are
relevant to the context.
 Similar to a human’s interaction with a website, a REST client hits an initial
API URI and uses the server-provided links to dynamically discover available
actions and access the resources it needs. The client need not have prior
knowledge of the service or the different steps involved in a workflow.
Additionally, the clients no longer have to hard code the URI structures for
different resources. HATEOAS allows the server to make URI changes as
the API evolves without breaking the clients.
 Let’s look at an example

8. HATEOAS

9.  In the preceding example, the response returned by the server contains
hypermedia links to employee resources 10/employees, which can be
traversed by the client to read employees belonging to the department.
 The advantage of the above approach is that hypermedia links returned from
the server drive the application’s state and not the other way around.

CONTINUE....

10. HATEOAS References
 There are two popular methods for specifying
JSON REST API hypermedia links:
 RFC 5988 (web linking)
 JSON Hypermedia API Language (HAL)

11. RFC 5988 (web linking)
 RFC 5988 puts forward a framework for building
links that defines the relation between
resources on the web. Each link in RFC 5988
contains the following properties:
 Target URI: Each link should contain a target
Internationalized Resource Identifiers (IRIs).
This is represented by the href attribute.
 Link relation type: The link relation type

12. JSON Hypermedia API Language (HAL)
 JSON HAL is a promising proposal that sets the conventions for expressing hypermedia
controls, such as links, with JSON or XML.
 The two associated MIME types are:
 Each link in HAL may contain the following properties:
 Target URI: It indicates the target resource URI. This is represented by the href attribute.
 Link relation: The link relation type describes how the current context is related to the target
resource. This is represented by the rel attribute.
 Type: This indicates the expected resource media type. This is represented by the type
attribute.

13. Sample JSON HAL
 A typical JSON HAL should look like the below response

14. Thank you for watching.
For queries please reach me out on twitter @avishekp86