Semantic REST APIs: From Dream to Reality


The dream: super-documented APIs with superpowers, as we mentioned, that offer us both extraordinary new possibilities and drastically reduced client-server coupling. How can we turn these APIs—currently still in the research phase—into an easy-to-produce must-have?

We have addressed this topic before: despite the great potential of Semantic REST APIs, all the ideas we have shared with you over the course of this inquiry are either research prototypes or our own visions.

Rest assured, as we have seen, it is quite possible to develop Semantic REST APIs today. Such development, however, is primarily a bet on the future (although “intellectual challenge” may be a close second), and standards that would put everyone on the same page are still waiting to be seen.

Why a bet on the future? Well, simply because articles, tutorials, and courses explaining this concept remain rare. And production-ready tools that take advantage of the richness of these APIs do not yet exist. In addition, implementing these APIs requires the development of features that will eventually require native support from frameworks.

In this article, we will outline our vision of the challenges that need to be addressed to encourage the field to lean more towards "easy-to-produce must-haves" and away from simple research projects.

1. Facilitate the production of Semantic REST APIs

Today, producing a REST API documented using Swagger is now fast thanks to frameworks such as Express, Django, Symfony, Spring, and Play!. And REST clients who help developers manually test them, such as Postman and Insomnia.

When it comes to producing a Semantic REST API, there is only one framework that makes the task fast: API Platform, based on PHP. On the REST client side, no one supports these new possibilities.

So what’s missing from these technologies to help us develop Semantic REST APIs?


In framework terms, in order for Semantic REST APIs to be easy to create, the following features are needed:

  • allowing developers to model business constraints, which are then solved by resource and request contexts that regulate the availability of each operation on a resource;
  • generating a description of the hypermedia controls available on the returned resource in response to the client's request;
  • using semantic vocabularies to document the API (Swagger does not);
  • allowing developers to describe the semantics of the data models and operations they provide, for example with annotations on classes and attributes;
  • supporting hypermedia and RDF document formats;
  • expressing the links between resources.

These features could be implemented by default in frameworks or proposed by third-party developers as a framework plugin or even in the form of a third-party library. Any company or developer can therefore contribute to checking items off on this list.

REST clients

Unlike frameworks, REST clients do not directly help developers write the code that makes APIs work. Instead, they help them test whether the API under development is working properly. This tool is very useful to developers on a daily basis.

By exploiting the metadata provided by the Semantic REST API (mainly documentation) to simplify and facilitate the navigation of the API by the developer, these clients are able to help him or her take their development work further.

In particular, REST clients can:

  • automatically generate pre-completed HTTP forms and requests from the descriptions provided by the API when the user clicks on a hypermedia control;
  • present users with definitions and types of data present in the RDF vocabulary to guide their interactions with the API.

2. Facilitate the consumption of Semantic REST APIs

REST and Semantic REST APIs are all HTTP APIs. They are consumed by other software, written in any programming language.

As developers, we use HTTP client libraries to make requests to APIs. Today, these libraries do not exploit the possibilities offered by Semantic REST APIs; they exploit either hypermedia or semantics, but never both. The libraries that support hypermedia can be found here. Interacting with web semantics requires two libraries: one to make SPARQL requests, and another to browse the RDF graph received in response. The latter will depend on the format of the document received.

As we saw previously, these APIs reduce client-server coupling to the semantics of the operations and data processed thanks to the richness of metadata and the technology that they provide. This is a major step forward towards significantly more flexible, maintainable, and scalable IS.

To exploit these APIs, HTTP client libraries will need to be enhanced with new capabilities, such as:

  • monitoring hypermedia controls and automatically generating HTTP requests to activate them;
  • retrieving a value in response to a request or choosing a hypermedia control based on one or more words from RDF vocabularies rather than a keyword;
  • dereferencing a resource related to the one that was just requested.

One of the challenges of these libraries is to offer enough RDF dictionaries so that users rarely have to search for them on their own, as well as to facilitate writing the search criteria for hypermedia or data controls in a response.

3. Build an ecosystem of useful (and fun) tools around Semantic REST APIs

Once we have the ability to create and consume these APIs easily, it will become possible to give our imagination free rein to create new tools and thus witness the emergence of a rich ecosystem such as the one in which RESTful APIs operate today.

In this section, we will share our ideas with you, ranked in the order in which we would like them to appear.

  1. Automatically generated visual interfaces
    We presented this example in our article entitled Hypermedia and Semantics in APIs: a powerful combination.

    Such a tool would allow non-technical users to make and test any Semantic REST API. It would no longer be necessary to develop graphical interfaces specific to one API and dedicated to performing demonstrations.

    We believe that this kind of tool would add a lot of value to the Semantic REST API ecosystem because it would make them more accessible than RESTful APIs.

  2. Automated functional and load testing tools

    We addressed this example in our article Hypermedia and Semantics in APIs: a powerful combination too.

    Implementing these tests is time-consuming and is often postponed repeatedly. Having tools to automatically generate them would save development teams time and allow them to obtain more information on how their developed APIs work, thereby enabling them to make better decisions.

    We believe that a tool of this type would increase the perceived value of Semantic REST APIs.

  3. HTTP clients capable of automatically replacing one API with another that meets the same functional requirements
    When you want to know what the weather's like in a certain place, or the address for a store, why use a specific API? Wouldn't it be better for users to always exploit the most reliable API with the fastest response time?

    With semantics, we could describe the desired information, and this library would take care of finding and integrating the API that best matches our needs, replacing it with another one whenever necessary.

    However, this tool requires that a central registry of descriptions and evaluations for Semantic REST APIs be made available online.

  4. Software capable of discovering scenarios for using an API
    As the number of HTTP operations offered by an API increases, identifying how to use the API and which operations can be composed becomes more and more difficult.

    The richness of Semantic REST APIs makes it possible to create software agents that can discover and present API usage scenarios. These agents would make APIs easier to access.

  5. Static documentation generator
    A framework for creating Semantic REST APIs would be capable of automatically documenting data models, operations, and links between resources. It would also be able to retrieve the semantic descriptions for all these elements. The latter regularly contains definitions written for humans.

    Based on this, it becomes possible to generate documentation (even in website form) that is richer than today's Swagger documentation and whose descriptions have been generated automatically. Developers would no longer need to write API documentation. Moreover, by being automated, it is guaranteed to be up to date.

  6. Middleware that automatically creates an API aggregating all the APIs from the information system
    The decomposition of an Information System (IS) into microservices introduces a certain complexity, because it becomes necessary to regularly query several services in order to carry out a complicated business process. Two solutions are possible: create another API that is attributed this role, or orchestrate several requests from the client.

    Semantic REST APIs allow you to create middleware that automatically generates a new REST or GraphQL API on top of all those making up the IS. This middleware only requires a list of IS service IPs and a mechanism for obtaining their static documentation.

Cross-disciplinary challenges

In order to create or improve the tools presented in the article, it is necessary for one or more document formats to become standard, like JSON has become standard for RESTful APIs. The same applies to RDF vocabulary.

Today, there are many formats that we previously addressed, but none of them are unanimously accepted. This is a problem for tool makers. The first challenge in this field is therefore to develop a standard.

Then, if we want to move towards a world in which APIs are easily replaceable, we will need a centralized registry for the description of Semantic REST APIs. In addition, in order to choose from them, a means of evaluating them all while minimizing human intervention and then making this evaluation machine-interpretable will also be required. These represent two additional challenges.

Finally, the last challenge we see is making these topics more accessible, mainly through articles, tutorials, and courses, as well as by raising awareness about the field in general.


To close this series, we have outlined the challenges and tools that we believe will reduce the cost of producing Semantic REST APIs and increase their value, notably by drastically reducing client-server coupling. Let us remember that, according to the IS professionals we interviewed, this coupling is the main technical problem for information systems.

In summary, we think that simplifying the creation of these APIs and subsequently their consumption is vital. And finally, we must take advantage of this simplification to create new tools that will accelerate development teams, make APIs more accessible, and provide information systems with additional flexibility. In addition, more educational resources are needed.

This last paragraph brings our series on Semantic REST APIs to a close. We hope that you have found it both informative and useful, and that you have enjoyed reading it as much as we have enjoyed writing it.