When talking about the REST subject, it's always worth discussing the Maturity Model, created by Leonard Richardson, which establishes three steps that a REST API should accomplish in order to be considered mature:

• Resources
• HTTP verbs
• Hypermedia controls: HATEOAS

In this section, we will focus on the last element. HATEOAS is intended to provide information about what we can do next, using additional Uniform Resource Identifiers (URIs) that are included as part of the resource.

Let's revisit our banking example, in order to explain HATEOAS from a practical view. Suppose that you have the following URI to query the customer's bank statements: http://your-api/customer/{customer_id}/bankStatements.

[
  {
    "accountStatusId": 1,
    "information": "Some information here"
  },
  {
    "accountStatusId": 2,
    "information": "Some information here"
  }
]

Also, let's suppose that the API has the ability to resend the bank statements or mark them as failed. With the information provided by the previously mentioned payload, there is no way to know about these operations. It's here that HATEOAS can be used, to let our API users know about the existence of these additional features. After applying HATEOAS, the payload will look as follows:

{
  "_embedded": 
  {
    "bankStatementList": 
    [
      {
        "bankStatementId": 1,
        "information": "Some information here",
        "_links": 
        {
          "markAsFailed": 
          [
            {
              "href": "http://localhost:8080/customer/
              1/bankStatements/1/markAsFailed"
            }, 
            {
              "href": "http://localhost:8080/customer/
              1/bankStatements/1/markAsFailed"
            }
          ],
          "resend": 
          [
            {
              "href": "http://localhost:8080/customer/
              1/bankStatements/1/resend"
            }, 
            {
              "href": "http://localhost:8080/customer/
              1/bankStatements/1/resend"
            }
          ]
        }
      }, 
      ...
        }
      }
    ]
  }
}

Note how easy it is to learn about the existence of these operations, which were hidden before applying HATEOAS as part of the API.