Netidee Blog Bild
Suitability of for Web API Annotations
How suitable is for Web API annotations (05.08.2019)
Förderjahr 2018 / Stipendien Call #13 / ProjektID: 3451 / Projekt: Dialogical Access to Lightweight Semantic Web Services

Like a website being a graph of documents, Web APIs can be also considered as a graph of resources that abstracts different collections of entities. Lightweight Web APIs conceptually consists of the following elements especially if they follow the REST principles:

  • Resource
  • Resource Identifier
  • Resource Method
  • Resource Representation and Metadata


mapping table

A resource is the main abstraction in a Web API. A client would read or modify a collection that resource represents by interacting with the API. A resource is identified with a URI. Each resource permits various HTTP methods for interaction. For instance, GET method is used for read-only operations and PUT is for creating a new entity. The data format used in the in the interaction can be specified within the request a client makes. When I first analyzed Actions, I have found out that the Action type contains properties that corresponds to these four main elements in terms of describing them semantically. A summary of this mapping can be found in Table 1. We can analyze a vocabulary in the context of semantic description of web services from three aspects, functional, behavioural and non-functional descriptions.

The functional description of a web service refers to describing its capabilities. In a lightweight setting, the functionality descriptions are usually quite limited, involving mostly the description of input and outputs of an interaction. Behavioural description involves with the order of interactions that need to be completed in order to complete a task. Non-functional aspects are specified on Web API level and involve properties like owner of the service, availability and price information.

I have seen that actions is fairly good in terms of describing functional and non-functional aspects. For functional description, it supports input and output parameters description and inverse properties to connect inputs and output. It contains many properties from the WebAPI and CreativeWork type for non-functional descriptions. Behavioural aspects are described with potential actions attached to responses that allow a client to achieve a task by using the follow-your-nose approach.

In summary, looks promising and with some extension it would be a suitable vocabulary for Web API description. One thing that is missing is a way to describe authentication properties. I have conceptualized an extension for that purpose. The next blog post will be about these extensions and how they can be defined with the help of SHACL. Meanwhile you can read more about the analysis of for Web APIs in our paper.


Diese Frage dient der Überprüfung, ob Sie ein menschlicher Besucher sind und um automatisierten SPAM zu verhindern.
    Der datenschutzrechtliche Verantwortliche (Internet Privatstiftung Austria - Internet Foundation Austria, Österreich) würde gerne mit folgenden Diensten Ihre personenbezogenen Daten verarbeiten. Dies ist für die Nutzung der Website nicht notwendig, ermöglicht aber eine noch engere Interaktion mit Ihnen. Falls gewünscht, treffen Sie bitte eine Auswahl: