HATEOAS for REST APIs

What is HATEOAS?

HATEOAS stands for Hypermedia as the Engine of Application State which is a constraint of the REST application architecture.

REST APIs has no service definition and no formal documentation. The best REST APIs don't need any documentation.

Just like websites have navigation from one page to another, REST APIs are able to do the same using HATEOAS.

In HATEOAS the response will carry links that provide links as to where to find the related resources.

This will let clients know all the things they can do with the received response and make the response navigable.

Eg: An user object may contain the URI to itself.

{
    "name": "John Doe",
    "links": [ {
        "rel": "self",
        "href": "http://localhost:8080/users/1"
    } ]
}

'rel' attribute here defines the relationship.

If we take a status object of a particular social network site, it could be represented as below.

{
   "title": "Hello World",
   "id": 40,
   "author": "John Doe",
   "links": [ {
                "rel": "profile",
                "href": "http://localhost:8080/profiles/1"
            } 
            {
                "rel": "comments",
                "href": "http://localhost:8080/status/40/comments"
            } ]
}

If the client requires the link to the comments of a particular status it is included here and will help the client navigate easily without having to figure it out.

Similar to how hypertext will navigate us through websites, Hypermedia will drive the client's interaction through the application state and hence called Hypermedia as the Engine of Application State.

This approach is basically how HAL is used in APIs.[2]

When to use it?

HATEOAS is used in hypermedia-driven sites.

A hypermedia site is a site that contains non linear information(graphics, audio, video etc.). It provides information to navigate the site's REST interfaces dynamically by including hypermedia links in the response.

This approach is not followed in SOA based systems usually as they have a fixed specification.

Why should we use it?

This approach will allow our API consumers know how to navigate through the API without any documentation and will not require them to hard code any URL to any related resource, instead it can be easily taken from the previous response.

How Paypal API uses this approach can be found at [1].

[1] https://developer.paypal.com/docs/api/hateoas-links/
[2] http://stateless.co/hal_specification.html

Comments

Admin panel of a Q & A Forum

In a Q & A Forum, when a user posts a question, it should be sent to the administrator for approval in case it contains inappropriate content. After approval it should be removed from this pending approval page and other users should be able to see the question afterwards. To enable this, we should maintain an approval column in our database table of records and for each record approval should be set to false by default. In the Pending approvals page only the records with approval=false should be displayed. Below is the MySQL statement for retrieval, $sql="SELECT * FROM topics WHERE approval=false"; To know which post was approved we should embed the post_id to the URL. And the relevant post should be updated as approval=true. Below is the complete code. <?php $sql="SELECT * FROM topics WHERE approval=false"; $query=mysqli_query($conn,$sql); echo '<form name="approve" method="p...

Getting Started with OAuth 2.0 using WSO2 Identity Server 5.3.0 and Playground2 Sample

This blog post provides step by step instructions for trying out OAuth 2.0 using WSO2 Identity Server . Here I use Identity Server 5.3.0 which is the latest released version by the time of this writing. The official documentation for this is available in https://docs.wso2.com/display/IS530/OAuth+2.0+with+WSO2+Playground , however for a beginner, it does not provide all the instructions such as creating a Service Provider with necessary configuration. However, by following the steps below, you can simply setup Identity Server and the playground2 sample webapp and test the entire OAuth 2.0 flow. Creating the Service Provider First step is to create a service provider in Identity Server. This is required because when a client application talks to Identity Server via OAuth 2.0, Identity Server has to identify the client and the incoming traffic. We set this configuration inside the service provider. Login to the Management Console of Identity Server and create a service provi...

Interacting with an Ethereum Smart Contract using Meteor and Ethereum

This blog post contains steps on how to interact with a specific contract on the blockchain extending the application created in the previous blog post [1]. Step 1: Add frozeman:template-var This is used since we use callback very often. This wrapper can be found at [2]. Give the following command in order to add it to our application. meteor add frozeman:template-var Step 2: Adding the balance to be viewed inside the template Alter your code as below. main.js main.html When you refresh the browser, you should get the below output without having to click the button. Step 3: Writing the Smart Contract in Solidity Solidity is the language that ethereum uses to write smart contracts. In order to write the smart contract for our application we will use the online Solidity compiler which can be found at [3]. Step 4: Deploying the Smart Contract Log in to the MetaMask and make sure you are on the testnet. Select 'Create' in the right side p...

Blog of Dinuksha Ishwari

Search This Blog