their own operations, wrapping the
resource information, and then invoke these through one of the HTTP methods
type of apis
Table 2 shows the distribution of the
different types of APIs. As it can be seen, approximately 95% of the APIs were
observed to follow REST architecture.
The information in the API developer
guides was thoroughly examined for 181 sub-categorical APIs under 8 selected
APIs. As it can be seen in Table 3 about 23.75% of APIs use optional parameters
which may or may not be Boolean. 33.70% APIs used Boolean as optional input
parameters, 18.23% APIs use query parameters. 76.79% APIs use path parameters,
whereas almost 83% APIs use a request body and pass input parameters to the
body. This has a strong effect on the matchmaking and invocation approaches,
since one API can be found or not depending on whether optional parameters are
taken into account or not. Similarly, if invocation is done on the basis of
default values, the output results can be drastically changed.
In general, JSON and XML are the most
widely used REST API output formats. The statement was proved through the
result of the performed analysis. As it can be seen in Table 4, there are two
main common output formats – XML and JSON. XML is provided in 41% of the cases
and JSON in 82%, and 27% APIs contain both JSON and XML together, as showed in
Table 4. Further output formats include CVS, Text, RSS, Atom, etc. These
results show that providing support for the use of XML and JSON addresses the
vast majority of the APIs.
If the output format of the API is designed to be flexible or to
support the majorly used output formats, the API can be considered
Most of the
APIs require some form of authentication to authorize the users for using data
through APIs. As it can be seen from Table 5, using OAuth token is by far the
most common way of authentication (54%). It is followed by 50% of APIs, which use
API key for authentication.
App ID, other
Similar to the output format, the form of authentication speaks well
of the API design.
up an HTTPS connection, client requests a certificate from the server to
establish the server identity. This creates a secure connection, but for the
server needs to qualify the authentic client, hence client certificate
authentication is used. With the use of client authentication, the client sends
its SSL certificate after it verifies the server identity. Then, the client and
server use both certificates to generate a unique key used to sign requests
sent between them 14.
provide SSL support
APIs that do
not provide SSL support
As it can be
seen in Table 6, only 60% of the APIs provide SSL support which is one
hindrance towards making the API RESTful or compliant to HTTP protocol.
this section I present results for API features, which are not strictly
necessary for directly supporting service tasks, but are useful when
implementing and using the APIs. As Table 7A shows, more than 82% of the APIs require
a request body to make a call to the API. Out of 181 APIs, 63% of them provide sample
requests and responses, which give valuable information to the developers about
the structure and the form of the request as well as of the retrieved results
and, therefore, ease development work.
I also found
that out of 8 APIs, 75% described the used error codes. Since HTTP provides a set
of standard errors, this represents a problem only for custom exception
implementations, where developers cannot determine what went wrong and whether
the error is due to an incorrect invocation, to missing credentials, etc.
require a request body
provide a sample request/response
provide an example
provide error or response codes
RQ1: What is the relation between
distribution of various structural metrics among the selected APIs?
Before achieving any
significant improvement in the RESTfulness of the REST APIs, we need to
understand a clear picture of its current scenario. The richness of the
description documents of the API, available information, its development
process, etc. is very essential to contribute in making a REST API more
compliant towards RESTful objective.
repositories and APIs may face significant challenges in using manual approach
to analyze data, which is also maintained manually-it may be prone to errors. From
my study, it can be clearly stated that majority of APIs follow REST
architecture. The description of input parameters is very flexible. JSON and
XML are establishing themselves as the main output formats. Even though there is
no specific constraint or guidelines for the format of the output, most APIs
nowadays give their results either in XML or JSON. Therefore, providing support
for using and processing only these two formats, would directly contribute to
the overall increase of Web API usability. Also, providing SSL support to the
API can make the communication more secure. Building the description documents
containing examples of request, response, response codes and error codes can be
of better help for the developers.
It was observed
that APIs within same category, tend to show few similar characteristics, e.g.
Most email APIs supported SMTP as output format. Mapping APIs had more number
of mashups than any other categories. Most of the APIs use some form of
authentication mechanism which is mostly either API key or OAuth.
RQ2: What are various design
patterns and anti-patterns of REST API?
The increased usage of REST for designing and developing Web-based
applications confronts common software engineering challenges. In fact,
likewise any software system, RESTful systems must evolve to handle new web
entities and resources, i.e., meet new business requirements. Even, the changes
in underlying technologies or protocols may force the REST APIs to change. All
these changes may degrade the design of REST APIs, which may cause the
introduction of common poor solutions to recurring design
problems—antipatterns—in opposition to design patterns, which are good
solutions to the problems that
software engineers face while designing and developing RESTful systems. Anti-patterns
might be introduced even in the early design phase of RESTful systems.
Antipatterns in RESTful systems not only degrade their design but also make
their maintenance and evolution difficult, whereas design patterns facilitate
A. Design patterns:
1. Content Negotiation: This pattern supports
alternative resource representations, e.g., in json, xml, pdf, etc. so that the
service consuming becomes more flexible with high reusability. Servers can
provide resources in any standard format requested by the clients.
2. End-point Redirection: The redirection feature
redirects clients to a new location to follow with one of the status code among
301, 302, 307, or 308, for old-deprecated APIs.
3. Entity Linking: This pattern enables runtime
communication via links provided by the server in the response body or via
Location: in the response header, to let clients find related entries at
4. Entity Endpoint: It is a facility of providing
multiple endpoints where each entity or a resource is uniquely identified.
5. Response Caching: Response caching is a good
practice to avoid sending duplicate requests and responses by caching all
response messages in the local client machine.
6. Uniform Contract: Based on three fundamental
elements: resource identifier, methods and media types.
7. Idempotent capability: It focuses on how can a
service capability safely accept multiple copies of the same message to handle
B. Design Anti-patterns: