Abstract— AREST API is an application program interface that uses HTTP protocol for makingrequests to a web server, using GET, PUT, POST and DELETE methods on the data.
ARESTful API, also referred to as a RESTful web service is based onrepresentational state transfer (REST) technology, an architectural style andapproach to communications, often used in web services development. REST is a very popular architectural choice for building Web-basedapplications due to its resources. Many worldwide used APIs are analysed not tobe fully compliant to the principles of HTTP.
In this work, I intend to studydescription documents of REST APIs and perform structural analysis. I will basemy findings on manually examining a body of publicly available API descriptions,and provide conclusions about common description forms, output types, usage ofAPI parameters, authentication details and level of reusability. This analysiscan be used as a basis for devising common standards and guidelines for APIdevelopment. This project aims to classify the patterns and anti-patterns aswell as mark their presence in few real-world APIs, if found. Keywords— REST, design patterns, anti-patterns, REST API structural analysisI. introductionA Web API is an application programminginterface (API) for either a web service or a web browser. It is a webdevelopment concept 1. RESTful HTTP is one of the architectural styles forbuilding web services.
Web services play a major role in the development ofloosely coupled component-based systems.Representational State Transfer (REST)is an architectural style that was first defined by Roy Fielding fordistributed systems such as World Wide Web. REST is a set of principles thatdefine how to use HTTP and URIs in an efficient functional manner. RESTfulservices are characterised by their relative simplicity and their naturalsuitability for the Web, relying mostly on the use of URLs, for both resourceidentification and interaction, and HTTP for message transmission 2. On thebasis of this simple technology stack, many websites like Facebook, Twitter,Google, Yahoo, Flickr offer easy to use public APIs that provide simple accessto some of the resources they hold, in order to allow reuse of data coming fromdiverse services.If the REST principles and guidelinesare strictly adhered while designing the application, the end system exploitsthe Web’s architecture to most.
REST is used in the context of HTTP webservices and APIs, heavily relying on the semantics of the communicationprotocol. The REST style has many appealing properties and principles thataddress the challenges and principles which modern web applications are facingtoday. Among many, there are few worth distinguishing – Uniform interface,Client/server separation, Stateless, Cacheable and Layered. Many APIs that claim to follow the RESTstyle are not RESTful or even REST compliant at all 345. Correct usage ofHTTP protocol is the first step to make the API – REST compliant, respectingits syntactical as well as semantic specification 6. The goal of this paperis to provide a structural analysis of selected REST APIs based on theircategorization.
Throughout this study, a set of metricshave been decided upon, and all the selected APIs will be analysed keeping themetrics in mind, to identify the main characteristics of today’s REST APIs aswell as their deficits with respect to compliance with the REST architecturalstyle. Knowing and analysing this data in detail may help to improve the stateof the art with purposeful solutions. The aim of this paper is to answer threedefined Research Questions, usingthe structural analysis of APIs and their design patterns/anti-patterns:· RQ1: What is the relationbetween distribution of various structural metrics and type/categories of APIs?What impact it has on API RESTfulness?Top widely used APIs’ description documentswill be analyzed and based on some metrics, the structural analysis would beconcluded to match it to some corresponding API characteristics. This researchquestion aims to answer if any relation can be established between the resultof the API structural analysis and its characteristics.
· RQ2: What are various design patterns andanti-patterns of REST API?Few research works have already defined a setof design patterns and anti-patterns of REST APIs, but there has not been anyconcrete list. This project work intends to study the defined patterns andsummarize them as well as research if any new pattern or anti-pattern isanalyzed and can be introduced.· RQ3: What is the possibility of presence of fewanti-patterns in the selected APIs?The analysis and result of research question 2is the starting point for this research question. This question aims to detectthe presence of defined list of anti-patterns in the APIs structure/design,that have been selected for this study and conclude their presence and impactof the anti-patterns on the success/popularity of the API. The paper is organized as follows: SectionII briefly describes the Related work, Section III describes the methodology/approachused for conducting this study, Section IV presents its analysis, while SectionV gives the results of the collected data. A summary of the main results and adiscussion of identified correlations and trends are provided in Section VI,concluding the paper.II. related workThere are few research works published,that talk about the structural analysis of the REST APIs.
The first researchand analysis of REST APIs was conducted in 5. The authors investigated a setof 222 Web APIs taken from apigee.com and ProgrammableWeb.
com, popular Web APIdirectories. The analysis was conducted manually and focuses on technicalaspects of the selected APIs that are renowned. I intend to manually selectAPIs from various categories and publish the results, as comparable to 5.Also, the security or response code aspects not covered in 5 are also underthe research lens in my project. Closest reference to my intended work is 7which is the analysis of APIs based on machine readable API descriptions. Theanalysis focuses on the structure of REST APIs and can be applied at designtime, to improve the design of APIs. This improvement could lead to the APIfollowing strict REST principles and being RESTful.
Researchers in 7, developand use a canonical model to enhance the probability of their analysis. The aimof my project is to continue analysis on the structure of APIs using thedescription documents and developer guides of wide range of APIs and provide anoverview or comment on the link between type/category of APIs with its designfactors. I would cover the top and renowned APIs specific to each category toensure diversification in analysis and results.It is important to design REST APIs ofquality for building well-maintainable and evolvable RESTful systems. In theliterature, various design concerns are evaluated by the means of anti-patternsconcept in terms of quality. The SOA (Service Oriented Architecture) communityhas defined the presence of various anti-patterns. There are many sources that listthe 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 RESTAPIs with respect to a set of five patterns and eight antipatterns.
Based onthe results, authors define a detection algorithm, both based on theobservation and investigation of request and response messages exchanged withan API. The work of 8 is continued and extended in 10. Here, the authorsselect a set of 15 REST APIs and concentrate on the analysis of URI structureusing a set of five linguistic patterns and anti-patterns. The general analysisapproach is the same as in 11. The whole process performed is semi-automatic.Each anti-pattern has a corresponding heuristics and detection algorithm, whichare 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 usedREST APIs.III.
approachProgrammableWeb API directory is one ofthe largest API directories online, containing 18370 Web APIs. I conducted thestudy by selecting APIs from the directory based on their categorization in thedirectory, to provide wide area of API description analysis. On www.
programmableweb.com, the APIs arecategorized 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 chosenbased on their ranks in the directory. The directory consists of relativelyvery large number of APIs which is not possible to be covered under the scopeof this study, hence I have taken 101 listed APIs under 12 categories from thedirectory.
The chosen categories are: Analytics, Email, Photos/Images, Social,Travel, File Sharing, Transportation, Blogging, Mapping, Banking, Health andVideo. 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 asthe data for this study.Each API description was analysed toobtain information in terms of few features, including general information ofthe API, its type, its input parameters, format of its output, Secure socketlayer support details and other documentation. This analysis was conductedmanually, 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.2. Type of Web API – It covers thearchitectural style of the Web API – which could be REST, RPC or hybrid. Theaim of this research is to identify the RESTfulness of the APIs, hence the onesthat are not REST can be eliminated.3. Input parameters – The APIs useoptional parameters, path parameters as well as query parameters, and whetherthe parameters are Boolean.4. Output formats – Though JSONand XML are the most used output formats, the description of APIs is analysedto know other used output formats.
5. Authentication mechanism –Various APIs use different types of authentication methods to provide access tothe API data. 6. SSL support – whether the APIprovides SSL support for the communication data for the connection to server.7. Other documentation – Does thedescription document provide examples of requests, response and error orresponse codes corresponding to an API. The focus of this study is to analysethese API features from description documents, as they play important role fordifferent aspects of API usage. The analysis approach involved sequence ofsimple steps.
First, 12 categories were browsed for picking up 5-8 top APIs in eachcategory, to ensure domain independent results. Later, each API page was opened,and general information was recorded. Secondly, the API developer’s guide wasvisited to find in depth about the API operations. Out of all 101 selectedAPIs, only 8 websites were selected for analysis of operation level data. Remaininggroup of data was collected for all 101 APIs.
The description forms and structures ofeach API had to be examined from scratch, without being able to benefit fromprevious API analysis, which made the whole process of this study slow. Basedon the general Web API information, the analysis highlighted that since alldetails are added manually to the Web API directory, some of the featuredescriptions were not always accurate. Sometimes, the URL of the documentationhad been moved or sometimes it was no longer available. Few APIs did notcontain information about their authentication mechanism or input/output types.This is indicative for the difficulties resulting from using directories basedon user entries. To determine the anti-patterns, Iselected top 5 APIs from the previously selected 101 APIs to manually analysetheir design, looking for anti-patterns.
The selected 5 APIs are of Dropbox,Twitter, Facebook, Team Viewer and Best Buy. With the help of POSTMAN extensionin chrome, I invoked the methods of these APIs and studied the responsereceived. After analysing the methods, requests and responses, thecharacteristics of each anti-pattern were checked for, and if found present-the results were recorded. Results show the presence of few anti-patterns invery famous and widely used APIs as presented in Results section V. Presence ofsuch anti-patterns does not create a state of error or issue. Instead, it is asort of warning or caution that can be followed to ensure the compliance ofREST APIs.
IV. analysisIn this section, the data collectedduring the study is described. The results are structured into 7 groups,according to different parts of API descriptions that were analysed. Each groupprovides valuable insights about separate aspects of the APIs and serves as thebasis for identifying common characteristics and drawing conclusions.
A. General API Information The first baseline of informationgathered here, directly by browsing to the API page of the directory, is thegeneral API information. It contains some details provided directly by the APIdirectory, such as the name of the API, its description, the category that itis assigned to, the URI of the API and the latest update of the description.Table 1 provides the recorded numbers for these features.
table 1general api information Description Maximum Minimum Average Categories under API 19 1 5 Number of operations 79 1 26 Number of mashups 2578 0 90 Each API taken into account, hadvarious functional categorizations under it. For example, Google AnalyticsManagement had few functional categorizations namely, Account Summaries,Accounts, AdWords Links, Custom Data Sources, Filters, Goals, etc. Each studiedAPI had minimum 1 functional category, 5 as average overall for all APIs.The general API information collectedalso 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 wasobserved to be 79, and 26 is the average number of operations under an API. Thisleads us to the conclusion that the majority of the APIs are moderate – neithersmall nor too large, and have very few operations, except large APIs like Google.A mashup is a web application, thatuses content from more than one source i.e. combines more than one API data, tocreate a single new service 1. ProgrammableWeb directory also presents the numberof mashups for each API.
The maximum number of mashups observed for an APIunder study was 2578, that of Google Maps. Average number of mashups for an APIwere calculated to be around 90. It was observed that mostly the APIs that fellunder the category of Mapping/Location had more than the average number ofmashups mentioned in Table 1.Finally, one observation madethroughout the analysis was that, since all details are added manually to the onlineAPI directory, some of the descriptions were missing, or not totally accurate.This is especially true for the URL of the documentation, which was sometimesmoved or no longer available, and for the authentication information, which wasvery often missing or generalized. Even though online API directories are theeasiest way to search for descriptions of wide range of APIs, there is a needfor developing approaches to automate the process of analysis based on theusage.
B. Type of APIs The selected APIs analysed from thedirectory were identified to be of RESTful and RPC architectural styles. RESTfulservices are defined as services, which conform to the representational statetransfer (REST) paradigm 6. REST is based on a set of constrains such as theclient-server based communication, statelessness of the request and use of auniform interface. A RESTful web service is commonly implemented by using HTTP,comprising a collection of uniquely identified resources and their links toeach other. In addition, RESTful services are characterised byresource-representation decoupling, so that resource content can be accessedvia different formats.
In comparison to RESTful APIs, RPC-style ones donot use directly the HTTP methods to access resources but rather define