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

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 schema.org 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 schema.org 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, schema.org 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 schema.org for Web APIs in our paper.