See discussions, stats, and author profiles for this publication at: https://www.researchgate.

net/publication/281287283

A Maturity Model for Semantic RESTful Web APIs

Conference Paper · June 2015

DOI: 10.1109/ICWS.2015.98

CITATIONS READS
6 3,520

2 authors:

Ivan Salvadori Frank Siqueira

Federal University of Santa Catarina Federal University of Santa Catarina
18 PUBLICATIONS   73 CITATIONS    95 PUBLICATIONS   441 CITATIONS   

SEE PROFILE SEE PROFILE

Some of the authors of this publication are also working on these related projects:

Ph.D. Thesis: Mapping Quality of Experience (QoE) through Quality of Service (QoS) with focus on Distributed Databases View project

All content following this page was uploaded by Frank Siqueira on 12 January 2016.

The user has requested enhancement of the downloaded file.

A Maturity Model for Semantic RESTful Web APIs

Ivan Salvadori Frank Siqueira

Department of Informatics and Statistics Department of Informatics and Statistics
Federal University of Santa Catarina Federal University of Santa Catarina
Florianópolis, SC - Brazil Florianópolis, SC - Brazil
[email protected] [email protected]

Abstract—Web APIs provide interfaces for interaction among represent fundamental characteristics for an efficient and re-
systems based on the existing infrastructure for hosting Web liable integration among systems. This work also identifies
sites and applications. The REST architectural style is the strategies for achieving the highest maturity levels of the
most employed approach for building Web APIs. However, the proposed model.
flexibility provided by REST may result in implementations with
low quality design, limited reuse and poor documentation. This The remainder of this paper is organized as follows. Section
paper describes a maturity model for classifying Web APIs, aimed II presents the main concepts required for understanding the
at promoting the adherence to REST architectural principles and proposed model. The related work is described in section III.
the adoption of semantic Web technology in order to improve the Section IV presents a new maturity model for Web APIs. Some
design, reuse and documentation of Web APIs. support technologies for Web API development are evaluated
Keywords-Maturity Model, REST, Web API, Linked Data, in section V. Finally, section VI summarizes the outcomes
Semantic Web of this work and points out some open areas for further
development.
I. I NTRODUCTION
II. BACKGROUND
REST is a very popular architectural style for integration This section describes the main concepts related to the
of Web-based applications, which allows sharing and reusing maturity model for Web APIs proposed in this paper.
information through distributed systems. Large-scale applica-
tions based on the REST principle must be implemented using
A. Semantic Web
the appropriate strategies and mechanisms in order to produce
systems that are easy to develop, reuse and maintain. The The Semantic Web [6] is an extension of the current World
integration interfaces provided by these systems, called Web Wide Web, in which data available on the Web is semantically
APIs, have an important influence on the characteristics of the described. The Semantic Web allows not only humans, but also
resulting implementation. machines to infer the meaning of data published on the Web,
and also facilitates data integration and reuse. It is a natural
According to Sjoberg, Dyba and Jorgensen [1], the vast evolution from a Web based on hypertext, targeted at human
majority of research studies are aimed at technology evolution, beings, toward a Web of data, which can be interpreted by
while technology evaluation is less investigated. Maturity mod- machines due to the association of published content with their
els provide a useful reference for evaluation, providing criteria semantic description. The combination of Web content with
for classifying existing implementations and the employed semantic descriptions creates an interconnected information
technologies. Heitmann et al. [2] present an empirical study structure known as Linked Data [7].
that evaluates the level of adoption of semantic technology for
application development and identifies the main technological Data available on the Semantic Web must be identified
challenges for its adoption. One of the main challenges iden- by HTTP Uniform Resource Identifiers (URIs) and must be
tified by the authors of this study is the lack of standards and associated with semantic descriptions built using standard tech-
guidelines for developing applications with semantic capabil- nologies recommended by the World Wide Web Consortium
ities. Therefore, a maturity model able to evaluate semantic (W3C). One of such standards is the Resource Description
applications can provide important guidelines for application Framework (RDF) [8], which is a method for information mod-
developers. In addition, Tahir and Macdonell [3] conclude that eling that can be employed for describing resource semantics.
most of the existing quality metrics are targeted at general- By using RDF, information is structured as triples subject-
purpose object-oriented systems. Other categories of systems, predicate-object. Subject represents the resource that is being
including Web-based systems, are not sufficiently explored. described, predicate is a characteristic of the subject, and object
The existing maturity models for Web API design found in is a value assigned to the characteristic of the subject. The
the literature [4] [5], though, do not take into account all available data must also have hyperlinks to related content, in
characteristics required for developing implementations with order to enable the navigation through the Web of data.
semantic support.
B. REST
This paper introduces a new maturity model for RESTful
Web APIs that evaluates three complementary and orthogonal REpresentational State Transfer (REST) is an architectural
dimensions: Design, Profile and Semantics. These dimensions style that defines a set of constraints aimed at improving the
performance, availability and scalability of Web-based dis- often limited to CRUD (Create, Read, Update and Delete)
tributed systems [9]. It is based on the traditional client-server procedures applied on resource data.
paradigm, in which requests issued by clients are executed by
a server. The best design strategies for modeling a Web API make
use of the original semantics of the data transfer protocol (e.g.,
A RESTful implementation is one that follows the con- HTTP). This paper identifies the existing strategies for model-
straints defined by the REST architectural style. REST defines ing a resource-based Web API and classifies them according to
a uniform interface for system components based on four the level of quality of the obtained implementation, resulting
constraints: resource identification, handling resources through in a maturity model to guide the construction and to evaluate
representations, self-described messages and Hypermedia as the quality of Web APIs.
the Engine of Application State (HATEOAS).
Resources are abstractions that represent information han- D. Semantic RESTful Web APIs
dled by RESTful applications. A resource must be identifiable The Semantic Web is based on principles and technologies
and accessible through a generic interface. Resources are not that may also be applied for the construction of semantically
directly accessed; instead, they are seen through a representa- enriched Web APIs. A Semantic Web API is one in which
tion, which is a snapshot of the state of a resource at a given data and operations are semantically described. APIs based on
time. Representations of a given resource may be available RESTful resources are able to profit from semantic technology,
in different formats, such as XML, JSON, HTML, and so given that there is no widely accepted standard for describing
on. Representations are obtained by issuing requests to Web data and operations provided by RESTful services.
services provided by a RESTful application.
One enabling technology for implementing Semantic
RESTful services must have stateless behavior, i.e., the RESTful Web APIs is JSON-LD [11], which is a W3C stan-
server does not keep information regarding the requests issued dard that extends the JSON format, allowing the addition of
by clients. This constraint is vital to improve the scalability Linked Data to resource representations. Resources described
of the system. Stateless behavior requires self-described mes- in JSON-LD are also valid JSON documents, allowing the
sages, i.e., the request must contain all the required information reuse of the existing libraries and tools for processing JSON
for being processed by the server. data. One of the main goals of JSON-LD is to allow the
construction of Web APIs that provide access to resources
The HATEOAS constraint defines that client interaction
that are semantically described by controlled vocabularies
must be guided through hypermedia controls, which provide
associated to a given application domain. The description
mechanisms for querying, storing and handling information on
of resources through a controlled vocabulary establishes a
resources. The HATEOAS principle implies that resource rep-
clearly defined context related to the information exchanged
resentations must provide not only resource information, but
with client applications, increasing their understanding of data
also hypermedia controls to guide client interaction, informing
semantics.
the operations that may be performed on the resource and
providing links to other resources which are made available Although JSON-LD represents a step forward toward the
by the server. addition of hypermedia controls to resource representations, it
does not provide means to describe the available operations to
handle resources [10]. An alternative that allows wider use of
C. Web API Design
hypermedia control is provided by Hydra [12], which extends
Web APIs consist in programmatic interfaces that provide JSON-LD with a vocabulary aimed at describing operation
access to Web Services for remote clients, allowing the con- semantics. Hydra allows the exchange of information in JSON,
struction of distributed applications based on the Web infras- using the semantic context provided by JSON-LD with the
tructure [10]. The design of a Web API has a direct influence addition of instructions to describe the operations supported by
on the quality of communication between a server and its a resource. Besides enriching the information made available
clients, given that it defines how information is modeled, through the Web API, Hydra offers mechanisms for document-
transmitted and interpreted. ing the whole set of resources accessible through the Web API.
The most adopted design styles for building Web APIs are
E. Web API Description and Documentation
based on Remote Procedure Calls (RPC) and on Resources.
Web APIs designed based on RPC style employ the HTTP Interaction with Web APIs may require the execution of
protocol to request operations, which are processed by a Web complex communication steps between a client and the server.
Service addressed by a single URI. The service receives a The communication flow is often composed by a sequence of
data payload and executes the requested operation using a requests that must follow a pre-established order in the aim
set of provided parameters. The RPC style does not follow of executing a complex activity in a given application domain.
the semantics of the HTTP protocol; services are requested A Domain Application Protocol (DAP) allows the description
through a HTTP POST method and the result of execution is of interactions among entities in a distributed system, guiding
contained in a payload sent to the client. the execution of a business process [13].
The design style based on Resources creates an interre- The HTTP protocol provides a uniform interface for han-
lated set of data, which becomes available through the Web dling Web resources among different platforms, standardizing
API. Each resource is addressed by a URI, which allows the semantics of protocol messages. However, HTTP semantics
the execution of operations on the resource. Operations are is not sufficient for describing all details of a given application
domain [13]. One solution for this problem is the adoption of REST
Profiles [10] to describe application and protocol semantics. A
profile describes a Web API in a format that can be understood Hypermedia Controls HTTP-based Type II
by humans and by software agents, allowing the construction
of intelligent and autonomous clients. HTTP Verbs HTTP-based Type I
Technologies such as JSON-LD and Hydra can be em-
Resources RPC URI-Tunneling
ployed for description of Profiles [10]. The documentation for-
mat for Web APIs offered by Hydra allows the description of
POX WS-*
resources with their corresponding properties and operations.
Complex interactions, though, cannot be described in a profile, (a) RMM (b) CoHA
requiring the use of hypermedia controls to guide the client.
Fig. 1. (a) Richardson and (b) CoHA maturity models
F. Quality Criteria
Meskens [14] presents a methodology to establish a di-
agnosis based on quality criteria, which helps developers to A. Richardson Maturity Model
identify if an application should be reengineered or completely
redeveloped. Flexibility, maintainability and testability are Richardson Maturity Model (RMM) [5] classifies Web
considered the main quality factors, which result in many APIs in four maturity levels according to their design, as shown
criteria such as: consistency, self-documentation, modularity, by Fig. 1(a). The lowest level consist in using HTTP just as
simplicity and conciseness. Metrics such as coupling, size and a data transfer protocol, without following the semantics of
cohesiveness, are also taken into account by the methodology. HTTP methods and REST architectural principles. The most
Four levels of abstraction are identified by the methodology. common format for data representation is XML, with a Plain
The implementation level identifies components (e.g., files, Old XML style (POX). Interactions are done in RPC style,
modules, variables) and explains how they are tied together, providing access to all services through a single access point.
abstracting the programming language chosen for system
The second level comprises Web APIs organized following
development. The structural level reveals how parts of the
the concept of Web resources. Information accessible through
system will influence the other parts. The functional level
the API is modeled as multiple resources. Every single re-
helps to explain the logical relationships among components.
source is uniquely identified and addressed, allowing the client
At last, the domain level provides an interpretation of the
to handle resources individually. Each resource can be accessed
functional behavior of components with concepts specific to
through its own set of operations.
the application domain.
According to Daud and Kadir [15] and Chahal and Singh The third maturity level enforces the conformance with
[16], the most employed metrics for evaluating the quality the semantics of the HTTP protocol. It requires the correct
of computer systems are cohesion, coupling and complexity. use of HTTP messages to handle resources accordingly, i.e.
Coupling measures the dependency among system modules. POST creates a resource, PUT modifies it, GET retrieves it and
Cohesion evaluates if the internal features of a module are DELETE removes the corresponding resource. HTTP status
closely related. Complexity derives from coupling and cohe- codes must also be used in response messages to describe with
sion, and can be defined as the difficulty to understand and consistency the result of operations performed on resources.
manage a system [17]. These metrics are employed by Tahir The highest maturity level requires adherence to the HA-
and Macdonell [3] and by Daud and Kadir [15]. The first TEOAS principle through the provision of hypermedia controls
two investigate the characteristics related to dynamic metrics, by the Web API. The provision of hypermedia controls allows
i.e., metrics applied during system execution [18]. The authors clients of the Web API to explore and navigate through
state that complexity and maintainability are the most explored resources without being tightly coupled to the internal charac-
aspects by dynamic metrics, while aspects such as testability teristics of the implementation.
and reusability are not given much attention. Daud and Kadir
[15], on the other hand, classify applications based on SOA B. CoHA Maturity Model
(Service Oriented Architecture) principles. These authors state
that modularity and low coupling have an important role Classification of HTTP-based APIs (CoHA) [4] defines
in SOA applications, given that these applications establish five maturity levels that can be associated with the design
service contracts and behavioral agreements. These authors of Web APIs, as shown by Fig. 1(b). The first level, named
divided the development process in four phases: requirements, WS-*, corresponds to implementations based on the SOAP
design, implementation and maintenance. However, the ma- protocol that employ HTTP as data transfer mechanism. In this
jority of metrics established for SOA systems focuses on the level, URIs are associated with services, and SOAP envelopes
implementation and design phases. encapsulate the required information for service execution.
This strategy presents high cost of adoption, maintenance and
III. R ELATED W ORK evolution, and may result in vendor lock-in due to the use of
proprietary technology.
Maturity models are useful to evaluate the quality of
software design and the resulting implementation. This section The second maturity level, named RPC URI-tunneling,
describes two proposals found in the literature that present requires the use of resources for modeling the API, without
maturity models for evaluation of Web APIs. enforcing operations based on the semantics of the data
transfer protocol. Despite allowing resources to be uniquely According to Chahal and Singh [16], quality is a measure
identified, this level does not grant access to multiple resource of user satisfaction, which is perceived by users based on
representations. This design approach results in high coupling external attributes of the system. Some outstanding external
between client and server, and constrains their capacity to attributes are: usability, integrity, maintainability and relia-
evolve independently from each other. bility. However, internal attributes - i.e., cohesion, coupling
and reusability - are of major relevance to the development
The third level, called HTTP-based Type I, requires han- team. The W S 3 maturity model sees client applications as
dling resources according to the semantics of the HTTP pro- users of the Web API, and establishes its internal and external
tocol. The API provides access to resources through represen- characteristics to fulfil client expectations. In order to reach
tations, allowing the use of different data formats. This design this goal, quality factors, metrics and criteria are distributed
requires the server to present stateless behavior, increasing the across the three dimensions of the W S 3 model.
scalability of the Web API. It has a low cost of adoption, but
the resulting implementation is still hard to evolve due to the
high coupling between client and server. A. The Design Dimension

The fourth level is named HTTP-based Type II and requires The Design dimension evaluates the structural character-
the use of self-described messages. Therefore, operations and istics of a Web API. This dimension focuses mainly on the
resources must be described at design time. Web APIs that structure of the information provided by the API. The Design
adopt this design strategy simplify client-server interactions dimension has four maturity levels. The lowest maturity level is
by providing a uniform interface. assigned to APIs with RPC design, which are strongly based
on services, and therefore do not comply with REST prin-
The fifth and highest level is called REST and follows all ciples. The Resources level corresponds to implementations
the constraints define by this architectural principle (i.e., re- in which data provided through the API is modeled in the
sources are identified and addressed, handled through represen- form of resources. This design cohesively groups data into
tations, messages are self-described and provide hypermedia separate units and simplifies information handling, allowing
controls). A high learning curve is required for adopting this the definition of operations for managing data. Up from
design strategy, but this initial cost is compensated by lower this level, APIs must have stateless behavior, resources are
maintenance and evolution costs, because changes in the Web handled through their representations and messages are self-
API do not interfere with client behavior. described. The following level, named Protocol Compliance,
is associated with Web APIs that respect the semantics of the
IV. T HE W S 3 M ATURITY M ODEL data transfer protocol. From this level upwards, resources are
handled through a uniform interface imposed by the adopted
The W S 3 maturity model, as shown in Fig. 2, has a cubic protocol. In spite of the focus of the Design dimension being
shape, in which the faces represent the evolution of Web APIs on the structural characteristics of the system, the Protocol
according to three dimensions, identified as Design, Profile and Compliance level evaluates behavioral aspects that aim to
Semantics. The Design dimension is based on the Richardson enforce communication patterns. At the top of this face of
Maturity Model, described in section 3.1, and represents the the cube is the Atomic Resources level, which corresponds to
different modeling strategies adopted for designing a Web API. the most mature design strategy. This level constrains access
The Profile dimension reflects the quality of documentation to resource properties separately. In this case, the smallest data
provided by the Web API. The Semantics dimension describes unit that can be handled by operations is the resource, and the
the level of support for semantic description of data and provided operations are able to alter all properties contained in
operations presented by the Web API. These three dimensions a representation. The Atomic Resources level is directly linked
are independent from each other and can be freely combined to information integrity, given that the constraints imposed by
to classify a given implementation. this design approach increase this quality criterion.
Semantic dimension Fig. 3 presents an example of atomic design, in which two
separate resources represent a single person. By adopting this
design it is possible to handle part of data associated to a per-
son separately, guaranteeing the atomicity of operations. Fig.
ed 4 illustrates an example with a representation of a person. The
nk
Li ata resource is composed by the following properties: FirstName,
D
FamilyName, BirthDate, Email and Password. CRUD opera-
tions can be performed on the resource through HTTP GET,
Atomic Resources POST, PUT and DELETE messages. However, the resource
Design dimension

provides a second set of operations to handle only properties

Protocol Compliance Email and Password. Despite respecting the semantics of the
n HTTP protocol, the adopted design does not guarantee the
Resources sio atomicity of operations performed on this resource.
en
m
RPC di
ile
of B. The Profile Dimension
Pr
A profile provides details on the structure and behavior of
Fig. 2. The W S3 maturity model resources handled through a Web API. Self-documentation is
one of the criteria presented by Meskens [14] that is directly
 FirstName encapsulate all resources required to execute a complex process
Email
FamilyName Password in a single meta-resource, allowing the execution of several op-
BirthDate erations with a single request. This approach is recommended
/webapi/person /webapi/credential if the client application has previous knowledge of all the
information needed for executing the whole process. Some
GET GET
POST POST processes, though, require information produced or provided
PUT PUT by the Web API during the execution of intermediate steps
DELETE DELETE of the business process. In this scenario, the process cannot
Entire Entire be invoked with a single request; therefore, a mechanism
Person Credential that guides the client through the execution of a sequence of
requests is required. Hypermedia controls added to resources
Fig. 3. Example: Atomic resource. may be employed to guide the client, teaching how to execute
operations on resources. This information can be added to
resource representations or to protocol headers. Fig. 5 shows
FirstName an example in which a resource Person is created through an
FamilyName HTTP POST request. The Web API sends a response saying
BirthDate that the resource was successfully stored and informing the
Email next step, which is creating a Credential for this person.
Password
/webapi/person POST

GET GET Person W

POST POST C
E
PUT PUT L next: POST: Credential B
DELETE DELETE I
E POST A
Entire Email N
P
Person Password T Credential
I
OK

Fig. 4. Example: Non-atomic resource.

Fig. 5. Orchestration through hypermedia control

related to the three quality factors (i.e., flexibility, maintain- The strategy based on hypermedia controls provides a
ability and testability). The profile is an effective way for self- mechanism for orchestrating operations that is not tied to a
documenting an API. Therefore, APIs that reach the maturity given application domain, given that the execution of busi-
levels associated with the Profile dimension have this quality ness processes is directly based on resources and operations.
characteristic. The proposed maturity model takes into account Despite the fact that this mechanism can be used in any
only profiles that can be interpreted by software agents. This application domain, there is still a high structural coupling
constraint reinforces the premise that the documentation must among resources handled by the Web API. This structural
be employed only for guiding clients at runtime, instead of coupling results from the fact that client applications must
guiding the developer (i.e., a human) at design time. correctly interpret resource representations, which may present
ambiguities, leading to handling errors. A viable alternative is
The Profile dimension can be evaluated combined with
to describe resource semantics by associating properties with
the other dimensions (Design and Semantic), and is divided
concepts described by a vocabulary or ontology.
into two maturity levels. Web APIs classified in the maturity
level Interaction Profile provide documentation describing the
semantics of the adopted communication protocol. This matu- C. The Semantic Dimension
rity level requires the description of all operations, including Web APIs described through semantic technology give an
their execution details, such as HTTP method, URI, supported increased understanding of the way in which resources are rep-
media types, required properties, and so on. The Domain resented and consumed. With the Semantic Web, information
Profile level requires the description of details specific to can be consistently handled, avoiding all sorts of ambiguity.
the application domain of the Web API, such as the order The semantic description of resources can be done through
of operation execution, pre- and post-conditions, etc. This the association of concepts defined by vocabularies shared
level may be reached using three different strategies: adding with client applications. Through this approach, vocabularies
hypermedia controls to resource representations; through pro- become the knowledge base, reducing the coupling among
tocol headers; or by documenting the Web API. Meskens [14] Web APIs and their clients to the conceptual level. The
considers that systems can be seen based on different levels Semantic dimension of the maturity model represents the use of
of abstraction. The Interaction and Domain Profile levels of semantic technology and is divided into two maturity levels,
the W S 3 model correspond, respectively, to the functional and which can be combined with the other two dimensions (i.e,
domain abstraction levels defined by Meskens. Design and Profile).
It is important to notice that complex business processes Heitmann [2] highlights that the adoption of the Semantic
may require several requests to manipulate multiple resources. Web for system development is in expansion, and that one
A possible strategy to hide the complexity from the user is to of the main reasons for its adoption is the ability to simplify
system integration. Despite the increased adoption of semantic vocabularies that have equivalent concepts. If more vocabu-
technologies, a large share of system integration efforts require laries are employed to describe resources, higher is the chance
human intervention. Heitmann states that one of the main of a client application being able to correctly understand
challenges in this area is to integrate different sources of the information carried by the resource. The capability of
heterogeneous data. The Semantic Web can provide a solution interpreting information is even higher when vocabularies are
for executing complex data integrations. Due to these facts, the shared by several other applications. This occurs with some
Semantic dimension of the W S 3 maturity model is an essential public vocabularies such as FOAF, Schema.org, DublinCore
part in the process of classifying and evaluating Web APIs. and DBPedia, among others. However, a proprietary vocabu-
lary can be employed to describe a very specific domain that
The Semantic Description level corresponds to APIs in
is not completely described by an existing public vocabulary.
which properties and operations of resources are semantically
Besides describing the semantics of properties, the example
described, allowing consumers to understand the information
shown in Fig. 7 identifies relationships among resources, which
and to perform operations appropriately (Fig. 6). Web APIs
are also defined by controlled vocabularies. One can notice in
that provide semantic description of resources result in less
the example that A person knows Another person that is the
coupled applications, given that the consumer can take into
author of A book. The use of Linked Data allows performing
account the semantic descriptions instead of relying on the
inferences that result in a higher level of information reuse.
developer to hard-code his/her understanding of the application
It is possible, for example, to infer that A person knows a
domain. However, the semantic description of properties and
book writer. The Linked Data maturity level does not imply
operations of resources incurs in a high cost, due to the high
using a standard data format, but Web APIs can adopt standard
modeling and development complexity.
technologies such as RDF and JSON-LD, among others, as
shown by Fig. 8.
FOAF
Vocabulary Person
1 {
foaf:Person FirstName 2 "@context": {
FamyliName 3 "foaf": "http://xmlns.com/foaf/0.1/",
foaf:firstName
BirthDate 4 "schema": "http://schema.org/"
foaf:familyName 5 },
6 "@type": ["foaf:Person","schema:Person"],
foaf:birthday Credential 7 "foaf:firstName": "A",
8 "foaf:familyName": "person",
Password 9 "foaf:knows": {
xfoaf:password_sha1sum
Email 10 "@type": ["foaf:Person","schema:Person"],
11 "foaf:firstName": "Another",
foaf:mbox 12 "foaf:familyName": "person",
13 "schema:author": {
14 "@type": "schema:Book",
15 "schema:name": "A book"
Fig. 6. Semantic description 16 }
17 }
18 }
The Linked Data level is reached when not only resources,
but also the relationships amongst them are semantically Fig. 8. Example: Resource representation in JSON-LD
described. Despite being possible to describe relationships
through the documentation of the Web API, the use of hy-
permedia controls results in a more beneficial solution, which
allows consumer applications to obtain this information on D. Classification and Selection of Web APIs
demand [13] [5]. The W S 3 maturity model provides classification mecha-
nisms that are helpful for the selection and composition of Web
APIs. Fig. 9 shows an example in which a client application
A
must invoke a service provided by a Web API. Multiple APIs
person
provide similar services, which are implemented differently.
FOAF The client application must choose among the available Web
Vocabulary
knows
APIs based on some criteria. The W S 3 maturity model can
Schema.org
Vocabulary
Another help in this process, identifying the maturity level of each
person existing Web API. As shown in Fig. 9, the Simple Web API
reaches levels D3-S0-P0, meaning that it fits in the third level
author
of the Design (D) dimension (i.e., Protocol Compliance) and
A that it does not provide support for Semantics (S) and Profile
book (P). By comparing this result with the levels obtained by the
other APIs, the client application can choose the one that is
Fig. 7. Example: Linked Data more suitable for its needs.
Classifying the maturity level of a given Web API is a
Fig. 7 presents an example of use of Linked Data, in which subjective action. Each client application has different needs
three resources are semantically described by two different that are fitted by a set of features. As a result, is difficult to
 D3-S0-P0 Simple [20] for describing resource representations and operations
Web API available through the Web API. WADL may be seen as an
Maturity approach for implementing profiles, however it is not able to
level? D2-S2-P0 Semantic describe the orchestration of requests required for executing a
Web API
Client complex business process.
Application
Self-documented
D2-S0-P2 Web API V. E VALUATION O F S UPPORT T ECHNOLOGY F OR W EB

Self-documented
According to Heitmann [2], the main obstacles for de-
D2-S2-P1 Semantic Web API
veloping semantic applications are: integrating noisy data;
mismatched data models between components; distribution of
Fig. 9. Selection of Web API based on maturity level application logic across components; and missing guidelines
and patterns. Maturity models can be employed as patterns and
guidelines for Web API development, aiming to increase the
quality of the resulting product. Software development tools
find a final number that represents the maturity level. It is up and frameworks can also take into account the evaluation and
to client application determine which characteristics are more classification criteria identified by maturity models in order to
relevant to achieve its goals. anticipate and mitigate obstacles during system development,
evolution and maintenance. This section evaluates some tools
E. Comparative Analysis and frameworks that provide support for Semantic Web API
Richardson and CoHA maturity models provide very useful development.
means for classifying the design of Web APIs. These maturity The vast majority of Web APIs are described only through
levels allow designers to identify the desired characteristics of text-based documentation, forcing users to read and understand
a Web API and guide its development and evolution. Despite these documents to write client applications. This fact results
providing a useful reference for evaluating the quality of Web in high-coupled implementations that are difficult to reuse.
API design, the maturity model proposed by Richardson does In this context, Maleshkova et al. [21] propose an approach
not describe ways to reach the highest maturity levels [19] to semantically annotate and classify the documentation of
and takes into account a limited set of quality attributes. Web APIs. The proposed approach employs the SWEET Tool
On the other hand, CoHA provides a more comprehensive [22] to add semantic descriptions to Web API documentation
alternative for Web API evaluation, which is not constrained through the execution of a semi-automated process.
to RESTful systems, taking into account other HTTP-based
distributed applications. CoHA also evaluates attributes such Gulden and Kugele [23] propose an approach to add
as performance, visibility, cost, evolution and maintenance, RESTful Web interfaces to legacy systems through the au-
among others. However, CoHA classifies RESTful Web APIs tomatic generation of Java code based on models. It generates
in a single level that requires full adherence to REST princi- resources based on the Domain Transfer Object (DTO) pattern,
ples. which are composed only by properties. The integration code
is isolated in a separate layer containing service classes. This
The W S 3 maturity model, which was introduced in this approach provides partial support for hypermedia control.
paper, takes into account characteristics that are not considered
by Richardson and CoHA, such as the use of profiles and Strauch and Schreier [19] propose a procedure composed
semantic descriptions. Profiles are vital for documenting Web by three steps for translating SOAP-based service interfaces
APIs that deal with complex business processes, while the into a RESTful Web API. The first step comprises the con-
use of semantic descriptions helps clients of the Web API version of services into resources, which are handled through
to understand and handle data correctly. The evaluation done POST operations (RPC style). The second iteration applies
by Heitmann [2] shows that only 11% of applications that a uniform interface with CRUD operations, which are in-
employ Semantic Web technology execute a fully automated voked through the corresponding HTTP request messages. The
integration process. Given that the Profile dimension considers third step adds hypermedia controls, defining the relationships
only documentation that can be read by software agents, among different resources. Support for HATEOAS is obtained
the documentation of Web APIs can be used together with through URI templates.
semantic technology to allow application integration without Salvadori and Siqueira [24] propose a framework that
human intervention. The W S 3 maturity model may be used allows resources to be annotated with semantic descriptions.
as a mechanism to promote automatic usability and compos- The framework is based on the JAX-RS specification, which
ability. In order to implement this feature, a Web APIs have to provides support for the development of RESTful Web Ser-
reach high maturity levels into different maturity dimensions. vices on the Java platform. Annotations are added to resource
Given that, integration without human intervention relies on properties and operations directly in the source code of the
characteristics from different dimensions. Web API. These annotations result in resource representations
in JSON-LD format with hypermedia controls based on Hydra
Richardson and CoHA maturity models do not clarify how
[12]. The framework generates the documentation of the API
the highest maturity levels can be reached. The W S 3 maturity
based on information obtained from the annotations added to
model, on the other hand, suggests the use of hypermedia
the source code.
controls, Linked Data and profiles to obtain high-quality API
design. The HTTP-based Type I level of the CoHA model re- Table 1 compares the maturity level of the support tech-
quires using Web Application Description Language (WADL) nologies for Web API development described in this section,
 TABLE I. M ATURITY LEVEL OF SUPPORT TECHNOLOGIES FOR W EB
API DEVELOPMENT. [5] J. Webber, S. Parastatidis, and I. S. Robinson, REST in Practice -
Hypermedia and Systems Architecture. O’Reilly, 2010.
Support Dimension [6] T. Berners-Lee, J. Hendler, and O. Lassila, “The semantic web,”
Technology Design Profile Semantic
Scientific American, vol. 284, no. 5, pp. 34–43, May 2001.
Maleshkova et al. [21] All levels None None
Gulden & Kugele [23] All levels None None [7] C. Bizer, T. Heath, K. Idehen, and T. Berners-Lee, “Linked data
Strauch & Schreier [19] All levels Interaction None on the web (ldow2008),” in Proceedings of the 17th International
Salvadori & Siqueira [24] All levels Interaction Linked Data Conference on World Wide Web, ser. WWW ’08. New York,
NY, USA: ACM, 2008, pp. 1265–1266. [Online]. Available: http:
//doi.acm.org/10.1145/1367497.1367760
taking into account the three dimensions of the maturity model [8] W3C, “Resource Description Framework (RDF) Model and Syntax
Specification,” http://www.w3.org/TR/rdf-syntax-grammar/, 2014.
proposed in this paper. All the described technologies allow
[9] R. T. Fielding, “REST: architectural styles and the design of network-
reaching any level in the Design dimension, given that they do based software architectures,” Doctoral dissertation, University of Cal-
not have a direct influence on the design principles adopted for ifornia, Irvine, 2000.
building the Web API. Only [24] and [19] reach Interaction [10] L. Richardson, M. Amundsen, and S. Ruby, Restful Web Apis.
level in the Profile dimension, and none reaches the Domain Oreilly & Associates Incorporated, 2013. [Online]. Available: http:
level. Just [24] provides full support for Semantic description //books.google.com.br/books?id=i3a7mAEACAAJ
of the Web API and its resources. Semantic annotations are [11] M. Lanthaler and C. Gütl, “On using JSON-LD to create evolvable
added to the Web API documentation by [21], but it does not RESTful services,” in WS-REST, R. Alarcón, C. Pautasso, and E. Wilde,
Eds. ACM, 2012, pp. 25–32.
add semantic information to resource representations.
[12] M. Lanthaler, “Creating 3rd Generation Web APIs with Hydra,”
in Proceedings of the 22Nd International Conference on World
VI. C ONCLUSIONS Wide Web Companion, ser. WWW ’13 Companion. Republic
and Canton of Geneva, Switzerland: International World Wide Web
The W S 3 maturity model aims to guide the development of Conferences Steering Committee, 2013, pp. 35–38. [Online]. Available:
http://dl.acm.org/citation.cfm?id=2487788.2487799
distributed applications that employ the Web as communication
infrastructure. The resulting model emphasizes the relevance [13] I. Robinson, “RESTful Domain Application Protocols,” in REST: From
Research to Practice, E. Wilde and C. Pautasso, Eds. Springer, 2011,
of efficient design as well as the provision of descriptive pp. 61–91.
information to obtain integration APIs that result in imple- [14] N. Meskens, “Software quality analysis system: a new approach,” in In-
mentations with low coupling and able to correctly understand dustrial Electronics, Control, and Instrumentation, 1996., Proceedings
the semantics of exchanged data. of the 1996 IEEE IECON 22nd International Conference on, vol. 3,
Aug 1996, pp. 1406–1411 vol.3.
The proposed maturity model helps to identify the main [15] N. Nik Daud and W. Wan Kadir, “Static and dynamic classifications for
goals to promote healthful interaction among clients and the SOA structural attributes metrics,” in Software Engineering Conference
Web API. First, the API must expose a data model based (MySEC), 2014 8th Malaysian, Sept 2014, pp. 130–135.
on atomic resources and the provided operations must respect [16] K. Kaur Chahal and H. Singh, “A metrics based approach to evaluate
protocol semantics. The Web API must also be described using design of software components,” in Global Software Engineering, 2008.
ICGSE 2008. IEEE International Conference on, Aug 2008, pp. 269–
profiling mechanisms, allowing software agents to understand 272.
how to interact with resources. At last, the use of Semantic
[17] H. Zuse, Software Complexity: Measures and Methods. Hawthorne,
Web technologies to describe resource representations accessed NJ, USA: Walter de Gruyter & Co., 1991.
through the Web API allows clients to dynamically find out [18] B. Cornelissen, A. Zaidman, A. van Deursen, L. Moonen, and
how data is represented, which operations are available and R. Koschke, “A systematic survey of program comprehension through
how resources relate to each other. dynamic analysis,” Software Engineering, IEEE Transactions on,
vol. 35, no. 5, pp. 684–702, Sept 2009.
As seen in section V, the existing support technologies [19] J. Strauch and S. Schreier, “RESTify: From RPCs to RESTful
for Web API development still do not promote high quality HTTP Design,” in Proceedings of the Third International Workshop
design, and have very limited support for building profiles and on RESTful Design, ser. WS-REST ’12. New York, NY, USA:
for semantic description of resources. It is expected that a new ACM, 2012, pp. 11–18. [Online]. Available: http://doi.acm.org/10.
1145/2307819.2307824
generation of support technologies looks into these limitations,
[20] M. J. Hadley, “Web Application Description Language (WADL),”
aiming to improve the quality of the resulting Web APIs. Mountain View, CA, USA, Tech. Rep., 2006.
[21] M. Maleshkova, L. Zilka, P. Knoth, and C. Pedrinaci, “Cross-Lingual
R EFERENCES Web API Classification and Annotation,” in MSW, ser. CEUR Work-
shop Proceedings, E. Montiel-Ponsoda, J. McCrae, P. Buitelaar, and
[1] D. I. K. Sjoberg, T. Dyba, and M. Jorgensen, “The future of P. Cimiano, Eds., vol. 775. CEUR-WS.org, 2011, pp. 1–12.
empirical methods in software engineering research,” in 2007 Future [22] M. Maleshkova, C. Pedrinaci, and J. Domingue, “Semantic annotation
of Software Engineering, ser. FOSE ’07. Washington, DC, USA: of Web APIs with SWEET,” in 6th Workshop on Scripting and
IEEE Computer Society, 2007, pp. 358–378. [Online]. Available: Development for the Semantic Web, colocated with ESWC, 2010.
http://dx.doi.org/10.1109/FOSE.2007.30
[23] M. Gulden and S. Kugele, “A Concept for Generating
[2] B. Heitmann, R. Cyganiak, C. Hayes, and S. Decker, “An empirically Simplified RESTful Interfaces,” in Proceedings of the 22Nd
grounded conceptual architecture for applications on the web of data,” International Conference on World Wide Web Companion,
Trans. Sys. Man Cyber Part C, vol. 42, no. 1, pp. 51–60, Jan. 2012. ser. WWW ’13 Companion. Republic and Canton of
[Online]. Available: http://dx.doi.org/10.1109/TSMCC.2011.2145370 Geneva, Switzerland: International World Wide Web Conferences
[3] A. Tahir and S. Macdonell, “A systematic mapping study on dynamic Steering Committee, 2013, pp. 1391–1398. [Online]. Available:
metrics and software quality,” in Software Maintenance (ICSM), 2012 http://dl.acm.org/citation.cfm?id=2487788.2488181
28th IEEE International Conference on, Sept 2012, pp. 326–335. [24] I. Salvadori and F. Siqueira, “A Framework for Semantic Description
[4] J. Algermissen, “Classification of HTTP-based APIs,” of RESTful Web APIs,” in Web Services (ICWS), 2014 IEEE 21th
http://nordsc.com/ext/classification_of_http_ based_apis.html, 2010. International Conference on, 2014, pp. 630–637.

View publication stats