Which technologies should you use to build Semantic APIs?
March 27, 2019, 5 min to read
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. Schema.org 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.
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
In this example, <code>”firstName”: “foaf:firstName”</code> is equivalent to<code>“firstName”: “http://xmls.com/foaf/spec/#term_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.
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     . The aim of ontology alignment is to create links and find similarities between multiple semantic vocabularies    . Matchmakers are “semantic API search engines”   . Certain frameworks, such as , 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.
Cartoon illustrations: semantic-ui-react
Code screenshots: carbon.now.sh