What The Heck Is Heatos?

Table of contents

• What the heck is Heatos?
• Why is HATEOAS useful?
• The one limitation of HATEOAS
• What has this got to do with tech writers?

What the heck is Heatos?

One of the things about APIs is that without accompanying documentation it's difficult to know what is available. On the other hand, most command-line tools, have the well know -h flag you can invoke to view all the options you can access. What if we could implement something similar to the command line -h option?

This is what Hypermedia as the Engine of Application State (HATEOAS) seeks to introduce. We all wish most abbreviations expand to tell us exactly what they mean, unfortunately, we don't exist in that world anyway back to the topic.

In a HATEOAS implementation, the API returns the requested response but then as part of that response, the requester gets back a list of other available URLs. This way the requester gets a list of endpoints they can further invoke.

✅ Wrap📋
01: {
02:     "profile": {
03:         "name": "John Doe",
04:         "age": 23,
05:         "userType": "admin"
06:     }
07:     "links": {
08:         "contributions": "/contributions/12",
09:         "score": "/score/12",
10:     }
11: }

In the above example, we get back a user profile and in addition to that, we get a list of links for different activities thus URLs to view the user's contributions and score. This means the developer doesn't even need to visit the docs to find those URLs.

Why is HATEOAS useful?

Well outside of the fact that once the user of API figures out one endpoint they can kind of navigate their way to other API functionalities, HEATEOAS makes it possible to automate API implementations, let me explain.

Since URL for fetching other resources is sent back in the response the developer can programmatically use those URLs and if they ever change the will be no need for the developer to change anything in their code. One area you will find HATEOAS used the most is to provide pagination links for endpoints that serve up large responses.

The one limitation of HATEOAS

HATEOAS is very good for implementing GET requests but not soo much for other kinds of requests that require data to be sent to the server. For those, you need to know the payload structure the server accepts and there is no defined way to do that with HATEOS. Long and short it's mostly limited to requests that involve just URLs. Some people find a hacky way to get around this by passing data as query parameters which sometimes leads to different issues depending on the data being sent to the server.

What has this got to do with tech writers?

Being able to identify, verify and point out APIs that implement HATEOS helps developers be certain about the structure of the response they get back.

The concept of self-documenting APIs has been around for a while and HATEOS is certainly at the forefront of that.

Here is another article you might like 😊 How to convert an OpenAPI specification into a NodeJS SDK