Semantically Enriched Open API Service Descriptions in the Cloud Nikolaos Mainas and Euripides G.M. Petrakis
Stelios Sotiriadis
School of Electrical and Computer Engineering Technical University of Crete (TUC) Chania, Crete, Greece {nmainas, petrakis}@intelligence.tuc.gr
Computer Engineering Research Group University of Toronto Toronto, Canada
[email protected]
Abstract—We propose an extension of the Open API specification (OAS) for the semantic description of RESTful services. We suggest that API descriptions (eg. on Clouds) be semantically annotated by associating OAS entities to entities in an ontology. The new approach, referred to Semantic OAS (SOAS) eliminates ambiguities and produces descriptions of RESTful services that are understandable by both, humans and machines. Moreover, SOAS descriptions are equivalent (i.e. can be translated) to an ontology. Therefore, SOAS services can be easily discovered (i.e. by other services), queried by Semantic Web query languages (e.g. SPARQL), checked by reasoners (e.g. Pellet) for consistency or inferring new (hidden) relationships and, finally, be used by service orchestration mechanisms. Index Terms—Web services; cloud computing; ontology; Open API; REST;
I. I NTRODUCTION The focus of this work is on improving the description of API services, and consequently allow for the implementation of efficient and accurate service discovery mechanisms on the Cloud. API services need to be understandable by machines and be described in a way that eliminates ambiguities and provides descriptions which are uniquely defined and discoverable (e.g. by other services). Since the majority of Cloud services are offered by means of REST architecture [1], we adopt Open API Specification 1 (OAS) as the main description language for Cloud services. OAS is a complete framework which is supported by a large set of tools 2 (Swagger editor, API interfaces with other frameworks like Javascript, Node.js, code generation etc.). OAS is good for human-understandable descriptions. In order for a machine to understand the meaning of OAS, a service description need to be formally defined and its content be semantically enriched. This work shows how OAS service descriptions can be semantically annotated by associating OAS entities to entities of an ontology (e.g. domain ontology). The new approach, henceforth referred to as Semantic OAS (SOAS) eliminates ambiguities in the original OAS descriptions and produces service descriptions that are understandable by both humans and machines. Moreover, this work proposes a mechanism for transforming SOAS descriptions to ontologies. This enables application of state-of-the-art query languages (e.g. SPARQL)
for service discovery and of reasoning tools for detecting inconsistencies and inferring relationships between services. For a detailed description of the SOAS approach please refer to [2]. Open API specification and the proposed SOAS approach are discussed in Sec. II and in Sec. III respectively. The mechanism for translating SOAS service descriptions to ontologies is presented in Sec. IV followed by conclusions and issues for future work in Sec. V. II. O PEN API S PECIFICATION (OAS) The Open API Specification provides a basic format for describing RESTful services. The specification offers a syntactic service description that is enriched with text descriptions (through the extensive use of description property) so that users may easily discover and understand the functionalities of the service and interact with it. An OAS description is structured in terms of objects the most important of them being: The Info Object provides non-functional information about the described service, such as the name of the service, contact information with service provider, and terms of the service. The SecurityDefinitions Object contains the security schemes that the service uses for authentication. The specification offers support for basic authentication, an API key and OAuth2’s common flows 3 . The Paths Object contains the relative paths for the service endpoints. Each Path item describes the available operations based on HTTP methods. The core of an OAS service document is the Operation Object. It contains all the needed information in order to construct HTTP requests to the service. In addition, it provides information regarding the HTTP responses that the service returns. The Responses Object contains all the expected responses of an Operation Object. It maps an expected response to a specific HTTP status code, describing the message content and HTTP Headers that an operation’s response may contain. The Definitions Object contains the data types (called Schema Objects) that are used to describe the request and response messages. A Schema Object can be a primitive (string, integer) an array or a model. For the definition of Schema Objects the specification is based on JSON Schema 4
1 https://www.openapis.org
3 https://tools.ietf.org/html/rfc6749
2 https://github.com/swagger-api/
4 http://json-schema.org/latest/json-schema-core.html
and introduces additional properties (such as composition and polymorphism) and also the description of XML data types. The Parameters Object contains the parameters that operations use and categorizes parameters into: • Path parameters are used in cases where the parameter’s value is part of operation’s path. • Query parameters are appended to the URI when sending a request. • Header parameters define additional custom headers that may be sent in a request. • Body parameters define the message content of a service request. A Body parameter refers to the data types defined in Definitions Object to describe the expected structure of the payload. • Form parameters are a special case of Body parameters, that describe the content of a service request when the media types “application/x-www-form-urlencoded” and “multipart/form-data” are used as the content type of the request. Listing 1 demonstrates how polymorphism support is provided using the discriminator property: A Person model uses the “gender” property as a discriminator in order to determine whether this is a model of a male or a female person. Listing 1. OAS Model polymorphism example definitions : Person : # A P e r s o n model t h a t w i l l be e x t e n d e d type : object properties : firstname : type : s t r i n g lastname : type : s t r i n g gender : type : s t r i n g required : − firstname − lastname − gender d i s c r i m i n a t o r : gender Male : # A Male model e x t e n d i n g t h e P e r s o n Model d e s c r i p t i o n : A r e p r e s e n t a t i o n o f a male p e r s o n allOf : − $ r e f : ’#/ d e f i n i t i o n s / Person ’ − type : object properties : height : type : i n t e g e r d e s c r i p t i o n : h e i g h t i n cms weight : type : i n t e g e r d e s c r i p t i o n : weight i n kgs required : − height − weight Female : # A Female model e x t e n d i n g t h e P e r s o n Model d e s c r i p t i o n : A r e p r e s e n t a t i o n of a female person allOf : − $ r e f : ’#/ d e f i n i t i o n s / Person ’ − type : object properties : eyesColor : type : s t r i n g required : − eyesColor
III. S EMANTIC O PEN API S PECIFICATION (SOAS) Taking advantage of the extension mechanism of OAS, we introduce additional properties to semantically annotate OAS properties. Table I summarizes these extension properties. TABLE I OAS EXTENSION PROPERTIES FOR SEMANTIC ANNOTATIONS Property x-refersTo
Applies to Schema Object & Parameter Object
x-kindOf
Schema Object
x-mapsTo
Schema Object & Parameter Object
x-collectionOn
Schema Object
x-onResource
Tag Object
x-operationType
Operation Object
Description It specifies the concept in a semantic model that best describes an OAS element. It specifies a specialization that exists between an OAS element and a concept in a semantic model. The property is mainly used to declare that a concept in a semantic model is too generic to describe the specified model, whereas a more specific subtype (if existed) should be considered more appropriate. It indicates that an OAS element is semantically similar with another OAS element. It indicates that a model describes a collection over a specific property. It denotes that the specific Tag Object refers to a resource described by a Schema Object. The property is used providing semantic information on the type of operation. The subtypes of the Action concept in the Schema.org vocabulary can be used as values of the property.
The x-refersTo extension property specifies the association between an OAS element and a concept in a semantic model. The property accepts a URI, that represents the concept in the semantic model. Listing 2 demonstrates how the property xrefersTo is used to semantically annotate a Person model and its properties. However, it is not always possible for a model to have a relation with an equivalent semantic concept, as a model may have a narrower meaning over the referenced semantic concept. For example, consider the Person model in Listing 2. If the model was defined to describe a specific group of people (e.g. teenagers), it would be inappropriate to associate the model with a generic concept such as the Person type of the Schema.org vocabulary, whereas a more specific subtype (if existed) should be considered more appropriate. In this case, the x-kindOf extension property is used denoting that the model is actually a subclass of the referred semantic concept. The property accepts a URI, representing the concept in the semantic model, and is only used for models in Definitions Object. Listing 2. Semantic annotations of Schema Objects definitions : Person : type : object x−r e f e r s T o : h t t p : / / schema . o r g / P e r s o n properties : firstname :
type : s t r i n g x−r e f e r s T o : h t t p : / / schema . o r g / givenName lastname : type : s t r i n g x−r e f e r s T o : h t t p : / / schema . o r g / familyName gender : type : s t r i n g x−r e f e r s T o : h t t p : / / schema . o r g / g e n d e r required : − firstname − lastname − gender
The x-mapsTo extension property is used to define OAS elements that share the same semantics. In a OAS service document, there are many elements that share the same semantic information that a human may understand but a machine cannot. In the following, for ease of discussion, we refer to the Swagger Petstore 5 service description. There is a semantic similarity among the petId property of the Order model and the id property of the Pet model. In addition, this semantic similarity also exists between the status property of the Pet model and the status query parameter. A human may easily infer these semantic similarities, either by the element names or by the description that may be provided. However, in order for a machine to act similarly to a human it is necessary to provide additional information, that specifies these relations. In SOAS, this is achieved with the x-mapsTo property. The x-collectionOn extension property is used to indicate that a model in Definitions Object is actually a collection. A collection (or a list) is defined in OAS using the array type. However, it is very common a collection’s definition to be enriched with additional properties and thus to be defined as an object type. Using the x-collectionOn property a model is considered to be a collection. The x-onResource extension property is used in Tag Objects in order to specify the resource that a tag refers. In OAS, tags are used to group operations either by resources or any other qualifier. If the tag is used to group operations by resources, a human may recognize that the referred resource is described by a Schema Object in Definitions Object. This information a machine is not able to infer and thus the x-onResource property is introduced and associates the tag with a Schema Object that describes a specific resource. Schema Objects can be semantically annotated using the x-refersTo property and thus refer to a semantic content with a specific meaning. Listing 3 demonstrates the usage of the x-onResource property on the Swagger Petstore service description. The property is assigned on a pet tag that provides information regarding the operations that are available for the resource that is described by the Pet model in Definitions Object. Listing 3. Excerpt from Swagger Petstore OAS service description tags : − name : p e t d e s c r i p t i o n : Everything about your P et s externalDocs : d e s c r i p t i o n : F i n d o u t more u r l : ’ h t t p : / / swagger . io ’ x−o n R e s o u r c e : ’ # / d e f i n i t i o n s / P e t ’ 5 http://petstore.swagger.io/
paths : / pet / findByStatus : get : x−o p e r a t i o n T y p e : ’ h t t p : / / schema . o r g / SearchAction ’ tags : − pet summary : F i n d s P e t s by s t a t u s d e s c r i p t i o n : M u l t i p l e s t a t u s v a l u e s c a n be p r o v i d e d w i t h comma s e p a r a t e d s t r i n g s operationId : findPetsByStatus produces : − a p p l i c a t i o n / xml − application / json parameters : − $ref : ’#/ parameters / statusQuery ’ responses : ’200 ’: description : successful operation schema : $ref : ’#/ d e f i n i t i o n s / PetCollection ’ ’400 ’: description : Invalid s t a t u s value security : − petstore auth : − ’ write : pets ’ − ’ read : pets ’
Finally, the x-operationType extension property is used in order to semantically specify the type of an Operation object. A request (an operation for OAS) is characterized by the HTTP method that it uses. However, the semantics of the HTTP methods are too generic and in the context of a service they may have a more specific meaning. For example, in the Swagger Petstore service description a GET request on the path /pet/findByStatus (Listing 3) is a search operation of pets based on their status. A human may refer to the description of the operation in order to understand its intended purpose, but a machine needs additional information as the HTTP method itself cannot provide such specific information. This information is specified by the use of the x-operationType extension property. The value of the property is a URL pointing on the concept that semantically describes the operation type. The Action6 type of the Schema.org vocabulary provides a detailed hierarchy of Action subtypes that can be used by the property. IV. T HE O PEN API O NTOLOGY SOAS extension properties allow an Open API document to become machine-understandable. Following this, an Open API document can be transformed to an ontology so that the representation of a service can benefit from Semantic Web tools (e.g. reasoners, query languages) enabling service discovery and service orchestration. Fig. 1 illustrates the structure of the proposed Open API ontology. The Document class represents the documentation and the entry point of the service. Similarly to the OAS structure, it provides general information (Info class) regarding the service, and also specifies the service paths and the entities it supports. A service path is described by the Path class containing the relative path for the service endpoint (using the pathName property). The Operation class corresponds to the Operation object in the OAS structure. 6 http://schema.org/Action
It contains information for expressing HTTP requests to the service as well as its responses.
type “array). Listing 4 illustrates how the “Person” model of Listing 2 is represented in the ontology. Listing 4. Representation of an OAS model in the Open API ontology ... r d f : t y p e openAPI : E n t i t y , owl : C l a s s ; openAPI : t i t l e P e r s o n ; : firstname , : lastname openAPI : s u p p o r t e d P r o p e r t y , : gender . : f i r s t n a m e r d f : t y p e openAPI : P r o p e r t y ; openAPI : t i t l e f i r s t n a m e ; openAPI : p r e d i c a t e ; openAPI : v a l u e T y p e x s d : s t r i n g ; openAPI : r e q u i r e d t r u e . : l a s t n a m e r d f : t y p e openAPI : P r o p e r t y ; openAPI : t i t l e l a s t n a m e ; openAPI : p r e d i c a t e ; openAPI : v a l u e T y p e x s d : s t r i n g ; openAPI : r e q u i r e d t r u e . : g e n d e r r d f : t y p e openAPI : P r o p e r t y ; openAPI : t i t l e g e n d e r ; openAPI : p r e d i c a t e ; openAPI : v a l u e T y p e x s d : s t r i n g ; openAPI : r e q u i r e d t r u e . ...
Fig. 1. The Open API Ontology
The Security class defines the security schemes that the specification supports. The Operation class refers to the defined security scheme through the SecurityRequirement class, which in the case of the OAuth2 security scheme contains the scopes that are needed in order to successfully execute the operation. Schema Objects can be associated with semantic concepts; it is feasible to express them in terms of classes, object and data properties and also capture all the information provided from the Open API document. The Entity class represents the classes that describe the models of an Open API service description and captures all the information contained in the models they describe. It specifies operations that are related to a class (supportedOperation) associated with the x-onResource extension property. In addition, it determines whether a class may contain additional properties (additionalProperties) of a specific type, described by a TemplateProperty and specifies the properties that a class contains (supportedProperty). The Property class represents the properties that a class definition contains. A Property specifies the supported property (predicate), its expected value (valueType) and also possible restrictions (e.g. a maximum value for a numeric property). In addition, Property class indicates whether the supported property is required or not. The Array class is introduced in order to denote properties that contain a list of values (properties of
Collections are represented in the ontology by the Collection class by specifying the members (member) of a collection.A “PetCollection” class is defined in the Open API ontology as a subclass of the Collection class. The “PetCollection” is also considered an Entity in order to describe its properties. OAS parameters are represented as classes for every parameter type. In Fig. 1, Header class, contains all the definitions of header parameters that are used in HTTP requests and responses. Body class defines the body parameters describing the expected message content of a HTTP request. FormData class represents the form parameters that are defined by the specification describing the message content of a HTTP request when the “application/x-www-form-urlencoded” and “multipart/form-data” media types are used. Parameter class defines all parameters that are attached to operation’s URL. The class is further organized in PathParameter and QueryParameter classes that refer to the corresponding path and query parameters of the specification. Parameters of an Open API service description (excluding body parameters) are represented in the Open API ontology similarly to a model’s property definition. V. C ONCLUSION We propose SOAS, an extention to Open API specification and we show that the yielding descriptions of RESTful services are equivalent to an ontology. SOAS descriptions are machine understandable so that they can be easily discovered by Semantic Web query languages (e.g. SPARQL), checked by reasoners (e.g. Pellet) for consistency and used by service orchestration mechanisms. R EFERENCES [1] Roy Thomas Fielding. REST: Architectural Styles and the Design of Network-based Software Architectures. Doctoral dissertation, University of California, Irvine, 2000. [2] Nikolaos Mainas. Semantically Enriched API Descriptions for Improving Service Discovery in Cloud Environments, December 2017.
