Hypermedia and Semantics in APIs: a powerful combination


When APIs are enriched with hyperlinks and semantics, we can create impressive apps. Good examples of this include self-evolving intelligent assistants and functional performance testing. In this article, we’re going to show you how Semantic REST APIs can be used.

This article is the sixth in our series on Semantic REST APIs. Previously, we showed you how hyperlinks can be used to enhance APIs. Then we dedicated an article to the benefits of adding semantics to APIs. Both possibilities offer solutions to different problems, reducing coupling and providing new capabilities.

Perhaps you’ve been wondering when the concept of Semantic REST APIs was going to come up? Well, here you go! Hypermedia APIs + semantics = Semantic REST. Now let’s look at the new capabilities this throws up.

Super APIs with super capabilities!

A Semantic REST API provides hyperlinks within each of its responses and semantically describes the data and metadata it supplies. This metadata includes all API documentation, i.e. a description of all its resources, operations and hyperlinks, as well as technical components such as authentication mechanisms, service-level-agreements, number of requests authorized each day, etc.

Let’s take a look at what we can actually do with these APIs, which feature particularly rich documentation that’s easy for a machine to interpret.

Generating graphical interfaces to interact with any API

Using semantics, we can decide how to display information returned by an API, for example, whether to use the name of a person or the title of an event as a page heading, or whether you need to display a table of financial results or maps of products on an e-commerce website.

However, semantics don’t provide links, making it impossible to navigate around a page. This is where hyperlinks in APIs make an interesting addition. If we have a list of items for sale, hyperlinks allow us to redirect the user to the product page when he or she clicks on the map. Or to the article, if these are maps of blog posts that have been published.

When you combine hypermedia and semantics, the machine can also identify the type of link being used. For example, it could be a link pointing to a process that needs to be carried out (e.g. placing an order) or a link to additional information, details about the item or to some other page. All this information allows us to generate an entire user interface without any prior knowledge of the API.

So how is this helpful? Well, if you’re a developer and want to present functions to your customers, you no longer need to create demo frontends. This saves a significant amount of time, allowing you to focus on the quality of the API. If you’re not a developer, you can now interact with all (Semantic REST) APIs. You don’t need a developer to help you anymore. You can just open up a web page, enter the URL of the API that interests you and then use it.

Identifying and running operations so actions can take place (spoiler: that’s what makes assistants truly intelligent)

If you’re a developer, you’ve probably already been asked to integrate API functionality across systems or websites. You’ve found the API you want to use, you’ve tried to run it, but it isn’t working… What you needed to do was to use other API services beforehand to make it available. But which ones? All you can do is spend several hours scouring the documentation to find out. Annoying.

If you aren’t a developer, someone may have already told you, “hey, you can do that on this website! Try it, it’s amazing!” So you go to the website, but you can’t find the function you’re looking for. In actual fact, you would have had to play around with the site settings beforehand, adding some information to your profile to activate the function. Again, annoying.

Hypermedia and semantics mean you don’t have to do any of that anymore. Semantics enable you to tell a machine what you want to do, like book a hire car. Then, a combination of hyperlinks and semantics invite the machine to browse the API services and identify all the initial steps that need to be taken to fulfill your request. All you need to do is provide it with the information it requires. For example, this might include the details it needs to set up your account on the car hire website. And you may have to agree to send on your driving license. Once you’ve done that, the car is booked. And everything was orchestrated by the machine when you asked it to “book me a hire car for this weekend”.

All this can be done in writing or orally. That’s why text bots and voice assistants, or chatbots, could become even more intelligent in years to come. Remember, nowadays, assistants are specifically programmed to carry out scenarios using previously integrated APIs.

Generating performance tests

Testing the performance of an API means testing the number of requests the server can accept per unit of time on three different levels: (i) the reading of one or more services, (ii) the writing of one or more services and (iii) according to scenarios that represent how the API is employed by users.

By combining hypermedia and semantics, a machine can determine a whole range of possible API user scenarios. This is because it knows how to compose and combine operations and work out the steps needed to carry out a particular process. Then, it can run those operations and processes using the hyperlinks provided.

Human intervention will continue to be necessary, we believe, for selecting relevant user scenarios. However, everything else can be automated.

Generating functional tests

Functional tests are used to make sure that a particular feature is performing as expected. Such a feature could be the creation of an account on a website that allows you to log in, for example.

Semantics mean you can describe a given feature. Then, by scanning the API documentation, a machine can identify the sequence of operations it needs to perform to produce this particular function. It will use hypermedia to work out whether its actions have made the desired operation available.

Using an approach stemming from Property-Based Testing, we could automatically test the API with a very wide range of random values. This helps us identify the values that do or don’t allow the API to function.

We could also test functional regressions. In other words, we could look at a function that has broken after an update. To generate tests, you only need to describe the function and not any related technical details. The machine will discover the latter. So, if the API changes, the machine can find a new way to carry out the function. If code has been written to do the test, this would need to be modified.

Obtaining enriched views of resources

An enriched view of a resource is when we add information from other internal and external sources/APIs to information we already have on that resource.

But it’s impossible to do this with a JSON API because it doesn’t contain any links. So, the machine can’t go and retrieve any more information.

If an API sends a response that contains hyperlinks, you can then follow those links, retrieve the data they point to and combine the whole lot in a single document or unique view.

Semantics help us intelligently complete data in a number of different ways. For example, they can help us to avoid duplicates because we can see when two links point to the same type of information. And they won’t retrieve undesirable information, such as the description of an API operation that would help you modify the resource, because this isn’t additional information on the resource itself.


As we’ve discussed in this article, the precision of metadata provided by Semantic REST APIs enables us to develop new, highly powerful tools. It also improves the performance of existing tools and makes them more precise. This means developers can save precious time.

We’ve also seen just how much we can reduce coupling between APIs and API customers. The experience and semantics become the focal point of the computer system.

The potential of these APIs goes far beyond the examples we’ve provided here. And we can’t wait to see what people studying the subject will come up with in the future. Could that be you?

Next week, we’ll be looking at the technologies that help create these kinds of APIs, as well as some of the tools that make it easier to select an API.