Study description documents of REST APIs and perform structural analysis.
Abstract. A 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 analyzed 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 a 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 the 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 characterized 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 diverse services. If the REST principles and guidelines have 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. 3 4 5 Correct usage of the 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 categorization. Throughout this study, a set of metrics have been decided upon and all the selected APIs will be analyzed 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 analyzing 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 the 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 the presence of few anti-patterns in the selected APIs. The analysis and result of the research question. 2 is the starting point for this research question This question aims to detect the presence of a 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 concludes the paper.
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 the technical aspects of the selected APIs that are renowned. I intend to manually select APIs from various categories and publish the results as compared to 5. Also, the security or response code aspects not covered in 5 are also under the research lens in my project. The 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 REST APIs.
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 a wide area of API description analysis. On www programmable web 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 analyzed APIs were chosen based on their ranks in the directory. The directory consists of a 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 analyzed 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 1 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. 3 Input parameters. The APIs use optional parameters path parameters as well as query parameters and whether the parameters are Boolean. 4 Output formats Though JSON and XML are the most used output formats the description of APIs is analyzed to know other used output formats. 5 Authentication mechanism Various APIs use different types of authentication methods to provide access to the API data. 6 SSL support whether the API provides SSL support for the communication data for the connection to the server. 7 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 a 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.
The 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 of 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 analyze 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 analyzing 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 REST APIs.
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 analyzed. Each group provides valuable insights about separate aspects of the APIs and serves as the basis for identifying common characteristics and drawing conclusions.
A 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. TABLE 1 GENERAL API INFORMATION. Description Maximum Minimum Average Categories under API 19 1 5. A number of operations 79 1 26. A number of mashups 2578 0 90. 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 a 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 understudy 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 a wide range of APIs there is a need for developing approaches to automate the process of analysis based on the usage B 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 constraints 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 characterized 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.