Why add hyperlinks to APIs?
March 8, 2019, 7 min to read
Imagine for a moment that all the links for websites you use have disappeared. In their place, you find a user guide on how to create URLs yourself as well as on how to create an HTTP request to comment on a Facebook photo. Let’s say that, for convenience’s sake, you use code to automate the creation of links. (It is 2019 after all!) And now every time the website is changed, you have to modify your code. Sounds absurd, doesn’t it? Nevertheless, this is the daily reality for developers using APIs. Together we are going to take a look at how adding links to APIs can avoid this.
APIs, REST and HATEOAS: What are we referring to?
A Web API provides a list of queryable services, such as receiving the daily weather forecast or posting a tweet. Each service is accessible via a URL which has been assigned to it, such as https://api.twitter.com/1.1/statuses/update.json for posting a tweet.
Today the majority of APIs are “RESTful”, which means they use REST architecture. Its creator Roy Fielding developed it with the aim of ensuring that the web is made up of performant, reliable and scalable systems. A scalable system is one that reuses functions provided by other systems (APIs), while not being affected when they get updated.
This last point is what we will be examining today. To be able to update itself without affecting its clients, a system needs to comply with a constraint that Roy Fielding called HATEOAS.
HATEOAS stands for “Hypermedia As The Engine Of Application State.” The idea is that links provided by the API guide the user as he or she uses the API. While this is the norm in HTML pages, that is not at all the case for APIs. This is a concept that many developers we have met have a hard time understanding when it comes to APIs, even though it seems completely natural to them when dealing with HTML.
Despite many API creators tending to describe their APIs as RESTful, 95% of them do not comply with the HATEOAS constraint. The majority of these APIs would be better described as HTTP APIs because they are accessible via HTTP but do not fully comply with REST. That said, it is no longer really possible to change how people use this term. This is why API creators who comply with HATEOAS call them HATEOAS APIs, or Hypermedia APIs (Hypermedia being the H in HATEOAS).
Let’s examine one last concept: Resources. Take the API of an e-commerce website as an example. It will probably have four resources: (i) users, (ii) items, (iii) orders, and (iv) the cart. Each resource has its own operations. For example, adding an item to the cart is one of the cart’s operations.
Let's get to the heart of the matter. This is the fun part!
To understand how links are used in APIs, we are going to consider how they are used in HTML. Take a look at the example in the image below.
In this image, you will find the five main uses for hyperlinks. Let’s take a look at them box by box.
- “Back to shop” indicates a link to another resource which it might be useful to access from the page being visited. This link is thus used as a recommendation.
- “EC-GO Tryout Bag” provides a link to the item in the cart, a separate resource as compared to the cart currently on display. Here the link is used to link another embedded resource to the resource being viewed.
- “Add gift code” is a link to an operation. This suggests that the user can add a discount code. If they were not logged in or had already added one, the button would no longer be displayed or would be greyed out. Here, a link is used to show the user’s access rights.
- In “payment details”, there are two interesting things to note. The first is that the link indicates the next step in the purchasing process being performed by the user. The user does not need to know the order of the steps required to place their order. All they need to do is click on next. The second is the form. It tells the user what info they need to enter to perform the payment operation. They are not confronted with a single text field requiring them to consult the terms and conditions of sale (the documentation) to find out what information they need to provide.
To generate this page, the API could have sent the following data:
If you are not used to reading code, don’t worry. The screenshot doesn’t show code containing logic or anything requiring complex interpretation. It just structures information. This is how you read it: Your order (your_order) is made up of elements identified by the codes “1234”, “5678” and “9ABC” (which sort of act like the items’ own social security numbers and are used to retrieve further information about them). 537 is the subtotal, and the shipping cost is 0. The rest is read in the same way.
Next, the code written in the website makes it possible to determine which links to display, how to generate the link to the product information sheet, what information to request in the form, whether a button should be displayed to give the user access to a specific page or action, and what the next step in the process is.
All information, except for recommendations, is also coded in the server because the server needs to verify that the site’s requests are valid and not attempted attacks. The code written for the web page, which contains rules that are highly specific to the API being used, creates a strong coupling with the server providing the API. When a web page (or any other software) uses an API, we call the page the API’s “client.” Client-server coupling can refer to multiple clients, since multiple pages or pieces of software can be clients.
As we saw in the first article in this series, this is the main factor standing in the way of technologically updating an IS. In our survey, it was also chosen by 30% of the participants as one of the top three most troublesome obstacles when trying to develop a new feature in a reasonable amount of time.
It presents the following problem: If the business rule changes, such as two steps in the process being reversed (e.g. payment and shipping), the code for both the website and server will then need to be modified. If instead of a single website there are dozens or hundreds of them, these are all clients that will need to be updated. Adapting a system to changes in the API being used happens to be a common task for developers.
By enhancing the API with the hyperlinks that the web page generates today, it is possible to remove all business rules from the web page. The page then becomes an interpreter of the API. It continues to function even if the API changes, provided that it was initially designed to be able to adapt intelligently. Here is an example of a file that the API could have sent to eliminate the coupling between a client and server:
It should be noted that the presence of a link indicates that the user has the right to perform the action or access the page in question. However, just like on an HTML page, if the link is not present, this means that the user does not have access rights.
The previous examples use hyperlinks to other web pages or the API’s HTTP operations without specifying the return format. The idea of hypermedia is to link resources from different media types, such as JSON documents, images and HTML pages. You can see this in the example below.
In this article, we have explained how hyperlinks can be used in APIs and shown how this can greatly reduce client-server coupling.
In the next post in this series, we will share the comparison we did of the nine types of message formats and the seven types of frameworks which make it possible to develop hypermedia APIs.