Spark the innovation within you.

When was the last time you did something new?


Which technologies should you use to build Semantic APIs?


Are you intrigued by the possibilities that machine-interpretable semantics open up? Would you now like to know which technologies will enable you to describe APIs semantically? Read on for more information.

In our last article, we introduced you to the things you can potentially do when machines are able to reason about the wording of APIs. To do this, APIs have to be semantically annotated.

Don’t forget that it’s possible to add semantics to your existing APIs and web pages, so instead of starting everything from scratch, all you need do is add to what you already have.

You will need two things: semantic vocabulary (or ontology) and the technology to annotate documents sent by your APIs.

Finding semantic vocabularies

We get semantics from the Semantic Web, which uses the RDF (Resource Description Framework) model to semantically describe data. We recommend you begin with this technology if you would like to learn more about this topic.

Start here or here to find the semantic vocabularies you need. is the most popular vocabulary resource currently available, because search engines use it to display rich metadata, for example. It was created by Google, Yahoo, Microsoft and Yandex.

If you can’t find the vocabulary you need, you will have to create it yourself. You can use Web Ontology Language (or OWL) to do this. This introduction will help get you started.

Semantics in HTML web pages

You can use a particular mechanism to semantically annotate the information contained on HTML pages. This is what the Open Graph Protocol does, and the mechanism’s name is RDFa.

Here is an example of an HTML page with no semantics.

And here is the same page after being semantically annotated. As you can see, all you need to do is import your selected vocabularies using the prefix attribute, then describe the data using the property attribute. RDFa opens up other possibilities that we won’t go into in this article.

Semantics in JSON APIs


Libraries are available in JavaScript, Python, PHP, Ruby, Java, C#, Go and Erlang.

In this example, <code>”firstName”: “foaf:firstName”</code> is equivalent to<code>“firstName”: “”</code>.

What do you do with the code for JSON APIs?

In the simplest possible terms, you can place all the semantics you use in your application in a single JSON-LD file. All you have to do then is add <code>“@context”: “link/to/this/json-ld/file” to all your JSON files.</code>.

If you want to be extremely thorough, you can create a JSON-LD template for each of your API’s resources. Place the semantic description of the resource in this template.

If, however, you would prefer this description to go straight in your code, you can add a <code>context</code> attribute to your classes. You can then use this attribute to place the code in your JSON file. Take a look at the example below.

The idea we like best is to add annotations on top of class attributes, rather than a context attribute. However, there is no library for that at the moment!

Using existing APIs’ semantics

Unfortunately, only research projects are using these semantics. While some of them do have libraries and technologies for automatically composing APIs, annotating them, shortening the semantic annotation process and so on, not many publish them as open source resources. Add to that the fact that they have been developed for academic experiments, rather than for developers’ use.

Developers need to offer open source libraries that use these semantics if we are to take the next step in this area.

Semantics were thought up by the creator of the world wide web.

The ideas behind the Semantic Web—and, by extension, machine-interpretable semantics—came from World Wide Web creator Tim Berners-Lee.

A whole range of technology has gone into the Semantic Web, such as RDF, SparQL, OWL, triplestores, RIF, RDF XML and JSON-LD.

From our point of view, the challenge we are facing at the moment when using semantics in RESTful APIs is the issue of creating tools for use in industrial projects. It is common for technology to encounter hurdles as is moves from its origins in research to an industrial setting.

Here are a few pointers if you would like to look at the related research in more depth. Mashups are composed of different APIs [1] [2] [3] [4] [5]. The aim of ontology alignment is to create links and find similarities between multiple semantic vocabularies [6] [7] [8] [9]. Matchmakers are “semantic API search engines” [10] [11] [12]. Certain frameworks, such as [13], make it easier to describe, find and compose Semantic REST APIs.

Feel free to explore the references these papers provide if you would like to read more about the subject. You can also log onto Google Scholar, type in the name of a paper and check out which other publications include it in citations.

Tim Berners-Lee is currently working on Solid, a project that has caught the attention of Fast Company, Vanity Fair and The Times. It aims to decentralize the web so that every user owns their own data. The idea is that we each store our data in a “pod”, and the apps we use access data from this pod when required. Of course, we would be able to control what they can and can’t access. Solid is based on the Semantic Web, and JSON-LD and FOAF in particular, both of which we talked about earlier.


In this article, we looked at technologies that enable you to semantically describe your APIs, as well as a few academic publications that will get you started if you want to know more about the issue.

In the next post in this series, we will tell you about what you can do when you combine hypermedia and semantics to create genuinely smart assistants, more flexible architectures and lots of tools that will help developers with their day-to-day tasks.

Image credits:

Icons: freepik from

Cartoon illustrations: semantic-ui-react

Code screenshots: