The Whats and Hows of Hypermedia APIs

29 July 2017 |

Hypermedia APIs

Building applications for different platforms, you have probably tried different sorts of APIs. Just in case you have not had a chance to enjoy the charm of hypermedia API, here is an article revealing the pluses you might find to be just for you.

The Good about Hypermedia APIs

The main goal of an application developer working with an API is to manipulate data and do something with the results. Most APIs leave out much information, which results in fellows thinking about how to work with the API and making mistakes when the interpretation is wrong. Hypermedia approach comes as a solution that reduces the time a developer spends to learn a new API and start using it productively. Plus, building such an API promises to be less mistake-prone which means that your application will more likely to work well at its entire lifespan.

What are Hypermedia APIs

Hypermedia APIs do not use RPC-style design pattern (a set of functions accepting parameters and returning objects) and work via links and forms / collections. Hyperlinking is what makes it possible to interact with data without spending much time to learn an API.

There is a number of registered hypermedia types (e.g. HAL, Collection+JSON, Siren, etc.) that are used as the message model for request and response payload. We are going to review the media formats in one of the next blog posts.

Hypermedia APIs are easier to work with. Along with some type of data as a response to a request, an application receives a list of links that defines what can be done next. In other words, a developer gets a precise idea of how to interact with the data due to the intent of the API provider.

The links returned are ordered hierarchically which makes using a hypermedia API highly organized. The path to the data needed is presented right there so that there is no more need for developers to grope for what they want to find.

What Else is Shiny Here

Hypermedia APIs are server-friendly. In the past, it was possible to pre-estimate the load on various elements of an application solution, which is no longer so easy to do today. The problem is that APIs are rooted into patterns that do not scale well. Hypermedia approach makes it possible to scale the solution so that it can keep running even if the load is heavier than anticipated.

One more benefit of using hypermedia APIs is increased reliability and stability. As there is a documented list of activities a caller can perform, the server spends more time managing data, for there is no more need to waste it to service errant requests. This also means higher security for the setup because there are fewer opportunities for outsiders to hack the system.

Some Tips

You may find some information that it is possibile to change request URIs because the caller will get a fresh URI list with each response. The issue here is that instead of rambling through the URI hierarchy a developer may want to bookmark URIs. With this considered, people with hypermedia API experience recommend not to change API URIs whereas adding new ones is fine. They also advise to document the API fully and provide the required client wrappers to ease making calls.

Using hypermedia APIs will save your time and effort as well as make both application and server more stable and secure. They are easier to work with though require more to be done before you can label them complete. Hypermedia APIs are fine to perform useful tasks today, but nobody knows what effect future changes will have upon them.

If you would like to find out more on how API2Cart works and what benefits for both developers and businesses it may provide, schedule a FREE consultation with our expert.