Rest API HATEOAS (Hypermedia as the Engine of Application State)

REST architecture allows us to generate hypermedia links in our responses dynamically and thus make navigation much easier. To put this into perspective, think about a website that uses hyperlinks to help you navigate to different parts of it. You can achieve the same effect with HATEOAS in your REST API.

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.

A REST client hits an initial API URI and uses the server-provided links to access the resources it needs and discover available actions dynamically.

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 hardcode the URI structures for various resources. HATEOAS allows the server to make URI changes as the API evolves without breaking the clients.

Let’s say we need to define an API that guides a client through a signature process. In this process after getting a Resource, the resource will include a Link indicating the following elements that are necessary. The plan is to add a signature link in this example:

{
    "documentID": 10,
    "documentType": "Contract",
    "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
    "links": [
        {
            "href": "10/signatures",
            "rel": "approval",
            "type" : "POST"
        }
    ]
}

The recommendation is to add a link to xsd/schema document which will define the structure of model attributes. e.g.

"links": [
    {
        "href": "10/signatures",
        "rel": "approval",
        "type" : "POST",
        "schema" : "/schemas/signature.xsd"
    }
]

Now the client can read the XSD document to find out about the model. This approach wouldn’t process the request but return the model XSD/schema document to the client. In this way, when client want to POST on 10/signatures, it may get the request schema by GET 10/signatures.xsd.

Resources

https://thereisnorightway.blogspot.com/2012/05/api-example-using-rest.html