An Analysis of RESTful APIs Offerings in the Industry

An analysis of RESTful APIs offerings in the industry Antonio Gamez-Diaz, Pablo Fernandez, and Antonio Ruiz-Cortes Universidad de Sevilla? {agamez2,pablofm,aruiz}@us.es Abstract. As distribution models of information systems are moving to XaaS paradigms, microservices architectures are rapidly emerging, having the RESTful principles as the API model of choice. In this context, the term of API Economy is being used to describe the increasing movement of the industries in order to take advantage of exposing their APIs as part of their service offering and expand its business model. Currently, the industry is adopting standard specifications such as OpenAPI to model the APIs in a standard way following the RESTful principles; this shift has supported the proliferation of API execution platforms (API Gateways) that allow the XaaS to optimize their costs. However, from a business point of view, modeling offering plans of those APIs is mainly done ad-hoc (or in a platform-dependent way) since no standard model has been proposed. This lack of standardization hinders the creation of API governance tools in order to provide and automate the management of business models in the XaaS industry. This work presents a systematic analysis of 69 XaaS in the industry that offer RESTful APIs as part of their business model. Specifically, we review in detail the plans that are part of the XaaS offerings that could be used as a first step to identify the requirements for the creation of an expressive governance model of realistic RESTful APIs. Additionally, we provide an open dataset in order to enable further analysis in this research line. 1 Introduction In the last decade, distribution models of information systems are evolving into XaaS [10] paradigms where customers no longer need to buy a perpetual license, host the software or maintain the infrastructure [5]. As part of this trend, the microservices architectures are rapidly emerging as they provide a flexible evolution model [7]. In particular, this architectural model proposes a division of the information system into a set of small services deployed independently ?This work has been partially supported by the European Commission (FEDER), the Spanish and the Andalusian R&D&I programs (grants TIN2015-70560-R (BELI) and P12–TIC-1867 (COPAS)) and the FPU scholarship program, granted by the Spanish Ministry of Education, Culture and Sports (FPU15/02980). which communicate each other using Web APIs that adhere typically to REST principles [6]. In this context, the term of API Economy is being increasingly used to describe the movement of the industries to share their internal business assets as APIs [21] not only across internal organizational units but also to external third parties; in doing so, this trend has the potential of unlocking additional business value through the creation of new assets [3]. In fact, we can find a number of XaaS examples in the industry that are deployed solely as APIs (such as Meaningcloud1, Flightstats2or Twilio3). In order to be competitive in this such a growing market of APIs, at least two key aspects can be identified: i) ease of use for its potential developers; ii) a flexible usage plan that fits their customer’s demands. Regarding the ease of use perspective, third party developers need to understand how to use the exposed APIs so it becomes necessary to provide a good training material but, unfortunately, several API providers do not often write a good documentation of their products [8]. Alternatively, in the last year, we found the promising proposal of the Open API Initiative4(OAI) whose aim is to support the creation, evolution and promotion of a vendor neutral description format for RESTful APIs and that is currently being backed by a growing number of leading industrial stakeholders. Conversely, from the usage plans perspective, to the best of our knowledge, do not exists a widely accepted model to describe usage plans including elements such as cost, functionality restrictions or limits. In this context, we can find some example of API management platforms in the industry (commonly known as API Gateways), which have tried to address the problem of usage plans modeling but they are typically constrained by their platform architecture and no interoperable usage plan specification is provided. For instance, Mashape presents a limited governance ecosystem, since it only allows users to define quotas and not rates. Figure 1 illustrates a real plan extracted from FullContact5, a real-world SaaS offering which includes an API that manages and organizes contacts in a collaborative way, it also matches emails addresses and tries to find as much information as available on the Internet to complete the profiles. Note that in this work, we focus on XaaS offering a RESTful API in order to access either fully or partially to the functionality they offer. In traditional XaaS, these actions are accessed using the graphic user interface. This example is composed of three plans, one of them is free whereas the remaining are paid. Focusing on paid ones, they have a fixed price that is monthly billed. Regarding the limits, for each resource, a quota is being applied; for instance, in the starter plan, only 6000 matches over Person are available. Nevertheless, an overage is defined, that is, it is possible to overcome the limit by 1https://www.meaningcloud.com/products/pricing 2https://developer.flightstats.com/getting-started/pricing 3https://www.twilio.com/sms/pricing 4https://www.openapis.org/ 5https://www.fullcontact.com/developer/ Fig. 1. Example of an API plan. paying a certain amount of money; in this case, $0.006 per each request. Regardless of the accessed resources, a common rate of 300 queries per minute is being applied. In this plan, there are not any functionality limitation, even the free plan has the same functionality that paid ones have. In this case, the free tier is regulated by limits such as quotas and rates. The main aim of this paper is to develop the first step towards an expressive, platform neutral, usage plan model that could be used to create open API governance tools. Specifically, this work presents a systematic analysis of the usage plans identified in a wide spectrum of real-world APIs; in doing so, the main contributions of this paper are: i) present a systematic method to analyze XaaS offerings in the industry including RESTful APIs; ii) undertake a comparative analysis of 69 industrial APIs selected from two widely used API directories, identifying the common trends related to the modeling of usage plans; iii) provide an open dataset that can be used to replicate our analysis and to be extended in further researches. This paper is organized as follows: Section 2 shows the methodology that we use in our study as well as the characteristics we analyze. Next, in Section 3, we discuss the results of the analysis. In addition, Section 4 shows the existing work related to this paper. Finally, Section 5 shows some remarks and conclusions. 2 Research method and conduct The study6presented herein was entirely conducted during the 2017 first quarter and it is a primary study in which we analyze real-world APIs. Whereas primary research data are collected from, for instance, research subjects or experiments, 6Data used in this study is publicly available at https://goo.gl/gQPDxz secondary studies involve the synthesis of existing research. Specifically, our work is based on the guidelines provided by Kitchenham and Charters in [12], adapting these guides about how to carry out secondary studies to a primary study. We consider that using these guidelines helps to systematize the research we are doing since they define a workflow directly applicable to primary research and give recommendations with the aim of avoiding undesired bias. In our work, we systematically analyze a set of characteristics in real-world APIs following the steps depicted in Figure 2. Fig. 2. BPMN representation of the research process. – SP01-Research questions definition. We start our systematic analysis with a series of motivating questions which will drive the investigation. We consider that these questions can pave the way for future research activities. Specifically, we define the following questions: •RQ01. What are the most common business models in the context of XaaS that offer a RESTful API? •RQ02. How are the plans, in terms of the characteristics that they have, used in XaaS that provide a RESTful API? •RQ03. Which regulations do XaaS offerings state over the RESTful APIs? – SP02-Sources identification. Based on the literature and the analysis of the industry that we have conducted, 10 API repositories were collected. Nevertheless, we have considered those ones which included more than 5000 APIs and whose last update date was in the year 2017, remaining 2 valid sources: S01-ProgrammableWeb7: with 17511 APIs distributed in 478 categories and S02-Mashape8with 7500 APIs distributed in 28 categories. Note that Mashape directory has been recently moved to RapidAPI9catalog, so subsequent analysis should be made over RapidAPI rather than Mashape. – SP03-Preliminary study. After a preliminary examination of API directories S01 and S02, the more popular categories in each one were identified. We did a percentile study over the categories and the number of users in each one. Particularly, we fixed P97 for S01 and P50 for S02. Additionally, we included some handpicked APIs, looking for these ones with complex plans. – SP04-Data extraction. We designed two different forms since the quality criteria have to be used to identify inclusion/exclusion criteria, according to the Kitchenham guidelines [12]. The first one10 tried to identify basic information about the analyzed API as well as information regarding the plans. The second one11 went in depth into the overage and both functionality and quota/rate limitations, including the API characteristics showed in Section 2.1. 30 students were given S01 and S02 API directories so that they chose two XaaS offerings following the eligibility criteria. They collected manually the required information in a session guided by the authors and they filled out the forms. In order to have a broader vision of the APIs offered in the industry, we defined an incremental process composed of three rounds. We started from defining strict eligibility criteria and the number of developers that the API has. Then we relaxed some criterion so that a new set of APIs was included. In the first round (R01) we limited the APIs selected from S01, considering only a certain set of categories12, according to its popularity (see SP03). In addition, we set a threshold of 50 registered developers in S01 and limited the APIs selected from S02 having, at least, 100 users and being in categories either paid or premium. In the second round (R02) we were informed by some students about they did not found any API according to the established search restrictions. At this moment, we determined to relax the criteria in S01, removing the 50 developers’ threshold. After finishing this round, we have collected 62 APIs. In the third round (R03) we started the guided session in class to fill out the form. Nevertheless, we noticed that there was a number of APIs without a clear plan, and students found quite difficult to find all the information that we asked for. At this point, we decided to start a new 7https://www.programmableweb.com 8https://www.mashape.com 9https://rapidapi.com 10 Available at https://goo.gl/rqwvH7. 11 Available at https://goo.gl/sbzXEh. 12 Mapping, social, e-commerce, mobile, search, tools, messaging, API, video, financial, cloud, payments, enterprise, analytics, data. API gathering session with the help of the instructors. After finishing this round, we harvested extra 28 APIs. – SP05-Subsequent analysis. We did a subsequent analysis in two different steps: i) manual data validation and classification: giving a result a set of 69 analyzed XaaS offerings with more than one plan. We detected some inconsistencies in some points that were manually reviewed and corrected; ii) ulterior results classification: in which we separated the data gathered regarding the source, obtaining 42 APIs from S01 and 27 from S02. 2.1 Analyzed attributes We developed a comparative framework based on 60 attributes grouped in 7 areas illustrating the traceability between the research questions and the gathered characteristics. Following, we describe each group of attributes. General information (see Table 1). We collected information about the API itself, including the name (GI01) and the source (GI02) where these APIs was selected from (i.e. Mashape or ProgrammableWeb); and the plans URL (GI03). API characterization (see Table 1). We distinguished two attributes, API type (AC01) and API maturity level (AC02), in terms of giving a more precise classification of APIs. Specifically, we propose a classification of four types for the API type:T01 if the XaaS offering does not provide any API at all; T02 when the XaaS offering does provide a non-RESTful API; T03 if the XaaS offering does provide as part of its offer a RESTful API, (e.g., a SaaS which allows customers to access their data in a RESTful way, but the primary access way is a GUI); and T04 if the XaaS offering is, actually, a RESTful API (e.g., an API to send emails or SMS). For API type T03 or T04, we identify a set of three API maturity levels:ML01 if the API does not define any limitations nor explicit Service Level Agreement (SLA); ML02 when the API defines limitations and/or explicit SLAs but they are not in the plans (i.e., the limitations are applied regardless of the selected plan); and ML03 if the API defines limitations and/or explicit SLAs depending on the selected plan. Pricing (see Table 1). We identify economic information of the API pricing including the currency (P01) in which clients are billed, the billing cycle (P02) and a set of statistics of the plan cost (P03,P04,P05). Business model (see Table 1). We consider the main primary business model (BM05) in the API, inspired by a number of works in the literature, as shown in section 4. Namely: free (FR), when no payment is needed; pay-as-you- go simple (PG-S), when you pay just for the usage you do (e.g., you pay per each request made); pay-as-you-go with intervals (PG-I), when the payment for each unit depends on the usage volume (e.g., the first 1K request cost $0.1 each, but the subsequent $0.05 each); tiered with fixed prices (TO1), when each plan has a non-variable price; tiered with overage (TO2), when existing plans with a certain price and limitations you can overcome the limits by paying an extra amount. We also gathered the number of plans (BM06) and discover the existence of discounts per annual upfronts (BM01), the existence of customs plans (BM03), the main limitation of the free plan (BM04); or the existence of a free plan (BM02). General information. RQ01 RQ02 RQ03 GI01-Name of the API. GI02-Source. X X X GI03-Plans URL. API characterization. AC01-API type. X X AC02-API maturity. X X Pricing. P01-Currency used. X X P02-Billing cycle. X X P03/P04/P05-Plan cost(max/min/avg). X X Business model. BM01-Existence of discounts per annual upfront. X X BM02-Existence of a free plan. X X BM03-Existence of custom plans. X X BM04-Main limitation of the free plan. X X BM05-Main business model. X X BM06-Number of plans. X X Table 1. First set of API analyzed attributes. Overage (see Table 2). We define overage as the extra cost in which a customer incurs when a certain limitation or set of limitations is exceeded (O01). The overage scope (O02) depends over what item the limitation is made (e.g., requests, the number of resources, etc.). Moreover, we collected data about the overage cost (maximum -O09-, minimum -O10- and average -O11- across the different plans) and the overage limit (maximum -O03-, minimum -O07- and average -O08- across the different plans), i.e., the amount of scoped data allowed per each overage payment. Furthermore, we consider the existence of an overage in every paid plan (O04) and we analyze whether in the same paid plan all the resources have an overage (O05) and all the resources have the same overage value(O06). Functionality limitations (see Table 2). We identify the limitations over the API functionality (FL01) and study the granularity: resource access granularity (FL02), if the limitation is applied to the resource endpoint (e.g. it is not possible to access some parts of the resource in some plans); HTTP method granularity (FL03), if the limitation is applied to a certain HTTP verb (e.g., it is not possible to make a POST in some plans) request body granularity (FL04), when the limitation is based on the specific payload sent to an endpoint. Furthermore, we identify the existence of a functionality limitation in every paid plan (FL05) and we analyze whether in the same paid plan all the resources have a functionality limitation (FL06) and all the resources have the same functionality limitations (FL07). Overage. RQ01 RQ02 RQ03 O01-Existence of an overage. X X X O02-Overage scope. X X O04-Existence of an overage in every paid plan. X X O05-In the same paid plan all the res. have an overage. X X O06-In the same paid plan all the res. have the same overage value. X X O03/O07/O08-Overage limit value(max/min/avg). X X O09/O10/O11-Overage cost (max/min/avg). X X Functionality limitations. FL01-Existence of functionality limitations. X X X FL02-Limitation granularity: resource access. X FL03-Limitation granularity: HTTP methods. X FL04-Limitation granularity: request body. X FL05-Existence of functionality limitations in every paid plan. X FL06-In different paid plans each one has the same func. lim. X FL07-In the same paid plan all the resources have a func. lim. X Table 2. Second set of API analyzed attributes. Quotas/Rates (see Table 3). We analyze two time-based limitations in the API, commonly known as quotas and rates. The main difference is the sliding window that rates have: whereas with quotas it is possible to define limits such as up to 1000 requests per day, with rates it is possible to express limits with a relative period of time, such as up to 100 requests in the last minute. Specifically, we identify the scope of these limitations: i) requests scope (Q02/R02) , ii) storage scope (Q03/R03); iii) resource scope (Q04/R04); iv) transaction size scope (Q05/R05) and other scopes not explicitly mentioned (Q06/R06). Moreover, we collected the value of the limitation (maximum -Q12/R12-, minimum -Q13/R13- and average -Q14/R14- across the plans) and periodicity. Furthermore, we consider the existence of a functionality limitation in every paid plan (Q07/R07), we analyze if in different plans each one has the same quotas/rates. (Q08/R08), whether in the same paid plan all the resources have a quotas/rates (Q09/R09) and, finally, if all the resources have the same quota/rate value. (Q10/R10). Quotas and rates. RQ01 RQ02 RQ03 Q01/R01-Existence of quotas/rates. X X X Q02/R02-Quotas/Rates over requests. X Q03/R03-Quotas/Rates over storage. X Q04/R04-Quotas/Rates over resources. X Q05/R05-Quotas/Rates over transaction size. X Q06/R06-Quotas/Rates over another scope. X Q07/R07-Quotas/Rates in every paid plan. X Q08/R08-Quota/Rates in all resources of different plans X Q09/R09-Quota/Rates in all resources of the same plan. X Q10/R10-Same quota/rate value for a given plan & resource X Q11/R11-Quota/rate periodicity. X Q12/R12/Q13/R13/Q14/R14-Quota/Rate value (max/min/avg). X Table 3. Third set of API analyzed attributes. 3 SP06-Results In this section, we present the results of the study grouped in three different blocks: i) attributes regarding the business model and pricing; ii) aspects related to limitations and overage application; iii) quotas and rates limitations. Due to the fact that there exist notable differences between the APIs and their governance models, we decided to perform a separate analysis regarding the source of the API: Mashape and ProgrammableWeb. In Figure 3 we observe that most of the APIs analyzed are, indeed, the XaaS offering (AC01). In the case of Mashape, all the APIs are T04. Regarding the maturity (AC02), in both cases, we observe that the defined limitations depend on the plan that the client selects. Note we have established a search protocol that picked primarily popular APIs from popular categories, a fact that explains this polarization in AC01 and AC02. A small number of APIs offer a discount per an anticipated payment or upfront (BM01), but the vast majority define a free tier with some specific limitations (B02). In addition, it is frequent to have a way to define custom plans by talking directly to the company (BM03). Regarding the business models (BM05), it is very likely for APIs from Mashape to have a tiered plan with an overage, in contrast to the ones from ProgrammableWeb, in which is common to have a tiered plan with fixed prices. It is remarkable that the more common billing cycle (P02) is monthly and the number of plans (BM06) oscillates between two and four. Figure 4 depicts the most interesting attribute analysis about how limitations are being applied in APIs. First, we observe that a high number limits the operations, rather than functionality or time (BM04). Secondly, from the providers that apply an overage if a certain limit is reached (O01), it is frequent that all the resources have an overage (O05), but it has not to be the same (O06). The most common scope (O02) is requests. On the other hand, some APIs apply limitations over the functionality (FL01), being more frequent in the APIs chosen from ProgrammableWeb. Most of the limitations are applied to the resource