Which technologies should you use for your Semantic REST APIs?
April 19, 2019, 8 min to read
In previous articles in this series, we’ve shown you how Semantic REST APIs (APIs combining hypermedia and semantics) can significantly reduce client-server coupling and provide new capabilities.
A Semantic REST API in its most complete form uses hypermedia to guide the user and is accompanied by a very detailed semantic description. But building a Semantic REST API takes a lot of work, so much so that you can choose to implement only those functions that you really need (or really want…let’s not get rid of all the fun!). And all this is still very new, so standards haven’t yet emerged. So, we can’t say: use this or that particular tech, it is THE industry standard, it’s very popular, really thorough, it’s definitely a good choice, and so on.
Instead, we’ll tell you which technology will be able to meet your requirements. First, let’s look at a maturity model developed for Semantic REST APIs that’s similar to the Richardson Maturity Model. Then we’ll show you the comparison tables we’ve put together and an online tool for simplifying the tech comparison process.
What types of technology are required?
You’ll need three different types of technology to design a Semantic REST API.
- A data interchange format (or media-type) that supports hypermedia controls and the addition of semantics;
- An interface description language (like Swagger) that provides the vocabulary and structure for describing your API using semantics;
- A framework to help you implement your API.
Choosing API functions
Every project has constraints and every team has its own particular expertise and objectives. And then there’s the issue of deadlines. How do you choose which functions to implement?
Well, you could get help from a maturity model. It’s a scale that defines different levels of maturity. Each level is assigned a number of functions or features. The higher the level of maturity, the more features the API offers. The Richardson model is the most popular scale for gauging the competence of your API. It has 4 REST maturity levels.
But did you know that the Richardson model used by most people isn’t in fact his version? Martin Fowler adapted the model, giving each level a new name. But he’s been criticized for implying that a level 3 API is more ‘mature’ than a level 1 API, when they actually fulfill different requirements. Neither is better, the best level depends on context. Critical review. Original model.
A model like this can help developers get a picture of the overall architecture envisaged. It helps you decide which functions you want to keep, and which ones you should cast aside. There’s nothing to say you need to completely disregard or comply with any particular level, as you can adapt the model to suit your project. In fact, when you choose a target level, you still need to refine your choice, one feature at a time.
Let’s now take a look at a model that goes further than the Richardson model to address Semantic REST APIs. It’s called the WS3 model.
This model evaluates the three dimensions of an API: design, profile and semantics.
The design dimension
The design dimension is based on the Richardson Maturity Model. It evaluates the structural and behavioral features of the API interface and the degree to which it conforms with REST architecture.
At level 0, the RPC level, APIs do not comply with REST principles.
To reach the Resources level, the API’s services must be organized according to the operations assigned to them and each resource must have its own URL. Communications must be stateless, resources handled through their representations and messages self-described.
The next level is Protocol Compliance. This is for APIs that respect the semantics of the http protocol, in particular, whether verbs are idempotent or not.
Level 4 is called Atomic Resources and can only be reached if the smallest data unit that can be handled by operations is the resource. In other words, if you have a user resource, you can’t have one operation to modify the email address and another to modify the postal address. Either email and address become separate resources, or there’s a single operation to modify the entire user resource. Only CRUD operations can then be performed.
The profile dimension
The profile dimension represents the wealth of documentation sent in API responses. Here, the definition of ‘profile’ matches the one provided in RFC 6906. The model only considers profiles that can be interpreted by software agents. As such, they must feature a structure and keywords that make scanning by algorithms possible. The individuals who developed this model state: “This constraint reinforces the premise that the documentation must be employed only for guiding clients at runtime, instead of guiding the developer (i.e. a human) at design time.”
To reach the Interaction Profile level, an API must describe several things. Firstly, the semantics (for the human) of the adopted communication protocol, but also all operations and related execution details. For example, the http method, the URI, supported media types, required properties and more. In other words, all the information relating to the functional description of the API.
The top level, Domain Profile, requires the description of the API application domain. This includes the order of operation execution, the conditions that make an operation available and the results produced (like sending an email, for example), etc.
You can get to this final level in three different ways: (i) by using hyperlinks to other resources (hypermedia), (ii) through the communication protocol headers used (usually http), or (iii) by documenting the API.
The semantic dimension
Here, the authors speak about machine-interpretable semantics, which we discussed in previous articles in this series.
The Semantic Description level means that all resource properties and operations are described semantically.
Beyond that, there’s the Linked Data level, which is reached when the API semantically describes relationships between resources. If you want to reach this level, using hypermedia controls at the same time is a good idea.
Comparing Semantic REST API technologies
No single technology is available to help you develop Semantic REST APIs that reach the highest WS3 maturity level. In the majority of cases, you’ll need to implement any missing functions by yourself.
That’s why our comparison includes technologies that offer no functions in certain categories or WS3 dimensions, but which could still be useful, depending on your requirements.
For easy comparison, we’ve devised a set of criteria to draw attention to the different functions and approaches of individual technologies. There are several different criteria listed in each WS3 category. That’s because there are a number of different technical solutions to help you get to the same level. However, when it comes to choosing technology for implementing the API, you need to accurately identify these different techniques.
Here you’ll find further information on the method we used to compile our comparison charts.
Data interchange formats
The table below compares existing data interchange formats to help you build Semantic REST APIs.
It also provides more detail than the table included in our previous article on hypermedia, because it lists Semantic Web technologies. It compares the following technologies: HAL, Collection+JSON, Siren, Uber, Mason, Json:Api, Atom, Turtle, RDF XML, OData and JSON-LD (to be combined with Hydra).
Interface description languages
The table below compares existing interface description languages to help you create Semantic REST APIs.
The table compares the following technologies: Rapido, Modeling RESTful Applications, Formal modeling of RESTful APIs using finite state machines, A model-driven approach for REST compliant service, Hydra, Atom Publishing Protocol + Atom Syndication Format, WSDL + SAWSDL, WADL, OpenAPI/Swagger, API Blueprint + MSON, hREST + microWSMO, RESTdesc, RADL, RAML and I/O Docs.
The table below compares available frameworks for building Semantic REST APIs.
The table compares the following technologies: Restfulie (ruby), Restfulie (.NET), Restfulie (java), API Platform, Spring HATEOAS, JAX-RS 2.0, A framework for the semantic description of restful web APIs and Ripozo.
Morice: choosing technology to help you build Semantic REST APIs in no time at all
To make it easier for you to choose the right technology when building a Semantic REST API (or a plain Semantic or RESTful API), we’ve created an assistant that you can access online.
You just need to choose the type of technology you’re looking for and then tick the boxes related to features you consider essential. Finally, you can score each feature depending on how important it is to you. This rating will then be used to calculate an overall score for each piece of technology and this will be used to order your list of results.
You can access the tool here.
So, there you go! You now have a maturity model, tables of comparison and a tool to help you choose which functions to incorporate in your future APIs as well as the technology you need to help you develop them.
The tables clearly show that the technologies currently available are all very different and still not that mature if you’re looking to develop Semantic REST APIs that can reach the highest levels of WS3.
In sum, Semantic REST APIs are a fascinating research topic with great promise for the future. However, there’s still a lot to do in terms of development.
Next week, we finish this series with an article on our vision of the future and the steps that need to be taken to further develop this subject on a larger scale.