Composing JSON-based Web APIs

Tweet about this on TwitterShare on FacebookBuffer this pageShare on RedditShare on LinkedInShare on Google+Email this to someone

We keep on working on our research work about the discovery of implicit schemas from JSON documents. Some months ago we presented the release of the webpage allowig you to play with the tool. We would like to give you an update about our advances. This time we have focused on how our tool can help you to compose JSON-based Web APIs. This work has been presented at ICWE 2014 conference, you can find the paper here and the slides here.

The use and composition of different APIs is in the basis of computer programming, and that is not different in the web development field. As we know, JSON-based Web APIs are becoming quite common in web development: nowadays almost every well-known Web API use JSON rather than XML (more than 47% of the APIs included in ProgrammableWeb return JSON data). Web developers have therefore to cope with the existing plethora of web APIs in order to create new web applications, which normally requires composing different APIs.

Our work is built on our previous contribution to study how schemas coming from different JSON-based web APIs can be composed. To this aim, we propose to apply a discovery process which first analyzes the domains behind each involved API and then identifies composition links among them. The discovered information is used to render a graph in which calculations can be made to assist developers to compose APIs (e.g., sequence diagrams can be generated). The next Figure illustrates our approach including the main two discovery phases (i.e., Domain Discovery and Composition Discovery) and facilities to realize the composition (see Composition Assistant).


As example, imagine we want to compose the Google Maps API and the TAN API (the API provided by the transportation public service in Nantes) in order to calculate a route in a map enriched with the set of bus/tram stops. In particular, we will use the Google Maps service to calculate the route to follow from a source point to a target one, which we will refer as routeCalculation service. This service receives as inputs: (1) the origin and (2) the destination of the route (expressed as addresses),and (3) whether a location sensor is available. The service returns a route to follow including the bounds and steps. On the other hand, we will use the TAN service to discover the bus/tram stops along the calculated route which we call stopPosition. The service receives a position determined by the latitude and longitude, and returns the nearest tram/bus stops. The following figure shows two example calls to these APIS.


In this example the developer must first explore these APIs and then study how they can be composed (if possible). The analysis of the inputs/outputs allows identifying the main concepts used in each API (i.e., the domain). For instance, routeCalculation uses addresses to specify both the origin and destination of the route. Regarding its output data, locations are represented by lat and lng to specify the latitude and longitude, respectively. On the other hand, stopPosition receives a location as input and returns a set of bus/tram stops. After this study, the developer may come up with a possible mapping involving the values representing locations in the output of routeCalculation and the input of stopPosition, thus enabling their composition.

As can be seen, composing JSON-based web APIs require deeply studying the involved APIs and also how to compose them, which is a time-consuming and hard task, in particular, when dealing with a number of candidate APIs. We propose to make this task lighter and shorter. We now show the main results of applying our process. The Domain Discovery process applied to the previous API examples will produce the following domains, represented as class diagrams:


From these domains, a composition graph is generated, were nodes represent either concepts (colored nodes) or attributes (white nodes), and edges connect either attributes/nodes or nodes (if there is an association in the domain). Dashed edges represent composition links and are drawn between those nodes detected as similar ones (we defined several similarity rules). The following figure shows the composition graph for the previous example. In this example, only one composition link has been detected:


From the previous graph, compositions can be detected by means of paths in the graph. To calculate a path, developers must specify both the input information (by selecting the concepts/attributes they have available) and what they want to get (by selecting the desired concepts/attributes)  A possible path between these two nodes is highlighted in the Figure, which indicates that a composition between these two APIs is possible. In particular, the composition can be performed calling the RouteCalculation service and using the attributes of the resulting Location concept to call to the stopPosition service.

Given this graph and the API domain models, several calculations can be applied to make easier the composition of the involved APIs and the understanding of paths in the graph. For instance, a sequence diagram can illustrate the calls and parameters to realize the composition. Next Figure shows the sequence diagram for our example. As can be seen, the developer is instructed to call the API services. It is also possible to detect loops and we also provide a possible mapping between the output/input parameters (see the annotation in the loop).


You can find the tool at Github as well as the update website including this new feature. We kindly invite you to play with the tool, any comment is welcome!




Tweet about this on TwitterShare on FacebookBuffer this pageShare on RedditShare on LinkedInShare on Google+Email this to someone


Your email address will not be published. Required fields are marked *