REST API is an application program interface that uses HTTP protocol for making
requests to a web server, using GET, PUT, POST and DELETE methods on the data. A
RESTful API, also referred to as a RESTful web service is based on
representational state transfer (REST) technology, an architectural style and
approach to communications, often used in web services development. REST is a very popular architectural choice for building Web-based
applications due to its resources. Many worldwide used APIs are analysed not to
be fully compliant to the principles of HTTP. In this work, I intend to study
description documents of REST APIs and perform structural analysis. I will base
my findings on manually examining a body of publicly available API descriptions,
and provide conclusions about common description forms, output types, usage of
API parameters, authentication details and level of reusability. This analysis
can be used as a basis for devising common standards and guidelines for API
development. This project aims to classify the patterns and anti-patterns as
well as mark their presence in few real-world APIs, if found.
Keywords— REST, design patterns, anti-patterns, REST API structural analysis
A Web API is an application programming
interface (API) for either a web service or a web browser. It is a web
development concept 1. RESTful HTTP is one of the architectural styles for
building web services. Web services play a major role in the development of
loosely coupled component-based systems.
Representational State Transfer (REST)
is an architectural style that was first defined by Roy Fielding for
distributed systems such as World Wide Web. REST is a set of principles that
define how to use HTTP and URIs in an efficient functional manner. RESTful
services are characterised by their relative simplicity and their natural
suitability for the Web, relying mostly on the use of URLs, for both resource
identification and interaction, and HTTP for message transmission 2. On the
basis of this simple technology stack, many websites like Facebook, Twitter,
Google, Yahoo, Flickr offer easy to use public APIs that provide simple access
to some of the resources they hold, in order to allow reuse of data coming from
If the REST principles and guidelines
are strictly adhered while designing the application, the end system exploits
the Web’s architecture to most. REST is used in the context of HTTP web
services and APIs, heavily relying on the semantics of the communication
protocol. The REST style has many appealing properties and principles that
address the challenges and principles which modern web applications are facing
today. Among many, there are few worth distinguishing – Uniform interface,
Client/server separation, Stateless, Cacheable and Layered.
Many APIs that claim to follow the REST
style are not RESTful or even REST compliant at all 345. Correct usage of
HTTP protocol is the first step to make the API – REST compliant, respecting
its syntactical as well as semantic specification 6. The goal of this paper
is to provide a structural analysis of selected REST APIs based on their
Throughout this study, a set of metrics
have been decided upon, and all the selected APIs will be analysed keeping the
metrics in mind, to identify the main characteristics of today’s REST APIs as
well as their deficits with respect to compliance with the REST architectural
style. Knowing and analysing this data in detail may help to improve the state
of the art with purposeful solutions.
The aim of this paper is to answer three
defined Research Questions, using
the structural analysis of APIs and their design patterns/anti-patterns:
RQ1: What is the relation
between distribution of various structural metrics and type/categories of APIs?
What impact it has on API RESTfulness?
Top widely used APIs’ description documents
will be analyzed and based on some metrics, the structural analysis would be
concluded to match it to some corresponding API characteristics. This research
question aims to answer if any relation can be established between the result
of the API structural analysis and its characteristics.
RQ2: What are various design patterns and
anti-patterns of REST API?
Few research works have already defined a set
of design patterns and anti-patterns of REST APIs, but there has not been any
concrete list. This project work intends to study the defined patterns and
summarize them as well as research if any new pattern or anti-pattern is
analyzed and can be introduced.
RQ3: What is the possibility of presence of few
anti-patterns in the selected APIs?
The analysis and result of research question 2
is the starting point for this research question. This question aims to detect
the presence of defined list of anti-patterns in the APIs structure/design,
that have been selected for this study and conclude their presence and impact
of the anti-patterns on the success/popularity of the API.
The paper is organized as follows: Section
II briefly describes the Related work, Section III describes the methodology/approach
used for conducting this study, Section IV presents its analysis, while Section
V gives the results of the collected data. A summary of the main results and a
discussion of identified correlations and trends are provided in Section VI,
concluding the paper.
II. related work
There are few research works published,
that talk about the structural analysis of the REST APIs. The first research
and analysis of REST APIs was conducted in 5. The authors investigated a set
of 222 Web APIs taken from apigee.com and ProgrammableWeb.com, popular Web API
directories. The analysis was conducted manually and focuses on technical
aspects of the selected APIs that are renowned. I intend to manually select
APIs from various categories and publish the results, as comparable to 5.
Also, the security or response code aspects not covered in 5 are also under
the research lens in my project.
Closest reference to my intended work is 7
which is the analysis of APIs based on machine readable API descriptions. The
analysis focuses on the structure of REST APIs and can be applied at design
time, to improve the design of APIs. This improvement could lead to the API
following strict REST principles and being RESTful. Researchers in 7, develop
and use a canonical model to enhance the probability of their analysis. The aim
of my project is to continue analysis on the structure of APIs using the
description documents and developer guides of wide range of APIs and provide an
overview or comment on the link between type/category of APIs with its design
factors. I would cover the top and renowned APIs specific to each category to
ensure diversification in analysis and results.
It is important to design REST APIs of
quality for building well-maintainable and evolvable RESTful systems. In the
literature, various design concerns are evaluated by the means of anti-patterns
concept in terms of quality. The SOA (Service Oriented Architecture) community
has defined the presence of various anti-patterns. There are many sources that list
the design patterns and anti-patterns like 8 9 and other sources on the Web.
The research paper 8 published the report of analysis of a set of 12 REST
APIs with respect to a set of five patterns and eight antipatterns. Based on
the results, authors define a detection algorithm, both based on the
observation and investigation of request and response messages exchanged with
an API. The work of 8 is continued and extended in 10. Here, the authors
select a set of 15 REST APIs and concentrate on the analysis of URI structure
using a set of five linguistic patterns and anti-patterns. The general analysis
approach is the same as in 11. The whole process performed is semi-automatic.
Each anti-pattern has a corresponding heuristics and detection algorithm, which
are applied to a set of request messages of the selected APIs. In this project,
I aim to collect and summarize the design patterns and anti-patterns and later,
manually study and discover listed anti-patterns in some selected widely used
ProgrammableWeb API directory is one of
the largest API directories online, containing 18370 Web APIs. I conducted the
study by selecting APIs from the directory based on their categorization in the
directory, to provide wide area of API description analysis. On www.programmableweb.com, the APIs are
categorized based on their functional applications, e.g. Social, Mapping,
Health, Videos, Banking, Artificial Intelligence, Advertising, Analytics,
Data-as-a-Service, Platform-as-a-service, etc. The analysed APIs were chosen
based on their ranks in the directory. The directory consists of relatively
very large number of APIs which is not possible to be covered under the scope
of this study, hence I have taken 101 listed APIs under 12 categories from the
directory. The chosen categories are: Analytics, Email, Photos/Images, Social,
Travel, File Sharing, Transportation, Blogging, Mapping, Banking, Health and
Video. Within the mentioned categories, APIs like Google Analytics, SendGrid,
Yahoo Mail, Gmail, MailChimp, Pinterest, Facebook, Twitter, LinkedIn, MySpace,
Google Plus, Trip Advisor, Uber, Tumblr, wordpress.org, etc. were considered as
the data for this study.
Each API description was analysed to
obtain information in terms of few features, including general information of
the API, its type, its input parameters, format of its output, Secure socket
layer support details and other documentation. This analysis was conducted
manually, without involving any tool. Each API was examined in terms of:
General description information
– This group of information consists of the API name, its description,
category, number of mashups, URL and number of operations.
Type of Web API – It covers the
architectural style of the Web API – which could be REST, RPC or hybrid. The
aim of this research is to identify the RESTfulness of the APIs, hence the ones
that are not REST can be eliminated.
Input parameters – The APIs use
optional parameters, path parameters as well as query parameters, and whether
the parameters are Boolean.
Output formats – Though JSON
and XML are the most used output formats, the description of APIs is analysed
to know other used output formats.
Authentication mechanism –
Various APIs use different types of authentication methods to provide access to
the API data.
SSL support – whether the API
provides SSL support for the communication data for the connection to server.
Other documentation – Does the
description document provide examples of requests, response and error or
response codes corresponding to an API.
The focus of this study is to analyse
these API features from description documents, as they play important role for
different aspects of API usage. The analysis approach involved sequence of
simple steps. First, 12 categories were browsed for picking up 5-8 top APIs in each
category, to ensure domain independent results. Later, each API page was opened,
and general information was recorded. Secondly, the API developer’s guide was
visited to find in depth about the API operations. Out of all 101 selected
APIs, only 8 websites were selected for analysis of operation level data. Remaining
group of data was collected for all 101 APIs.
The description forms and structures of
each API had to be examined from scratch, without being able to benefit from
previous API analysis, which made the whole process of this study slow. Based
on the general Web API information, the analysis highlighted that since all
details are added manually to the Web API directory, some of the feature
descriptions were not always accurate. Sometimes, the URL of the documentation
had been moved or sometimes it was no longer available. Few APIs did not
contain information about their authentication mechanism or input/output types.
This is indicative for the difficulties resulting from using directories based
on user entries.
To determine the anti-patterns, I
selected top 5 APIs from the previously selected 101 APIs to manually analyse
their design, looking for anti-patterns. The selected 5 APIs are of Dropbox,
Twitter, Facebook, Team Viewer and Best Buy. With the help of POSTMAN extension
in chrome, I invoked the methods of these APIs and studied the response
received. After analysing the methods, requests and responses, the
characteristics of each anti-pattern were checked for, and if found present-
the results were recorded. Results show the presence of few anti-patterns in
very famous and widely used APIs as presented in Results section V. Presence of
such anti-patterns does not create a state of error or issue. Instead, it is a
sort of warning or caution that can be followed to ensure the compliance of
In this section, the data collected
during the study is described. The results are structured into 7 groups,
according to different parts of API descriptions that were analysed. Each group
provides valuable insights about separate aspects of the APIs and serves as the
basis for identifying common characteristics and drawing conclusions.
General API Information
The first baseline of information
gathered here, directly by browsing to the API page of the directory, is the
general API information. It contains some details provided directly by the API
directory, such as the name of the API, its description, the category that it
is assigned to, the URI of the API and the latest update of the description.
Table 1 provides the recorded numbers for these features.
general api information
Categories under API
Number of operations
Number of mashups
Each API taken into account, had
various functional categorizations under it. For example, Google Analytics
Management had few functional categorizations namely, Account Summaries,
Accounts, AdWords Links, Custom Data Sources, Filters, Goals, etc. Each studied
API had minimum 1 functional category, 5 as average overall for all APIs.
The general API information collected
also delivers some valuable insights about the granularity, i.e. the number of operations,
of the APIs. The maximum number of operations present under a single API was
observed to be 79, and 26 is the average number of operations under an API. This
leads us to the conclusion that the majority of the APIs are moderate – neither
small nor too large, and have very few operations, except large APIs like Google.
A mashup is a web application, that
uses content from more than one source i.e. combines more than one API data, to
create a single new service 1. ProgrammableWeb directory also presents the number
of mashups for each API. The maximum number of mashups observed for an API
under study was 2578, that of Google Maps. Average number of mashups for an API
were calculated to be around 90. It was observed that mostly the APIs that fell
under the category of Mapping/Location had more than the average number of
mashups mentioned in Table 1.
Finally, one observation made
throughout the analysis was that, since all details are added manually to the online
API directory, some of the descriptions were missing, or not totally accurate.
This is especially true for the URL of the documentation, which was sometimes
moved or no longer available, and for the authentication information, which was
very often missing or generalized. Even though online API directories are the
easiest way to search for descriptions of wide range of APIs, there is a need
for developing approaches to automate the process of analysis based on the
Type of APIs
The selected APIs analysed from the
directory were identified to be of RESTful and RPC architectural styles. RESTful
services are defined as services, which conform to the representational state
transfer (REST) paradigm 6. REST is based on a set of constrains such as the
client-server based communication, statelessness of the request and use of a
uniform interface. A RESTful web service is commonly implemented by using HTTP,
comprising a collection of uniquely identified resources and their links to
each other. In addition, RESTful services are characterised by
resource-representation decoupling, so that resource content can be accessed
via different formats.
In comparison to RESTful APIs, RPC-style ones do
not use directly the HTTP methods to access resources but rather define