GraphQL is a query language and thereupon-based paradigm for implementing web Application Programming Interfaces (APIs) for client-server interactions. Using GraphQL, clients define precise, nested data-requirements in typed queries, which are resolved by servers against (possibly multiple) backend systems, like databases, object storages, or other APIs. Clients receive only the data they care about, in a single request. However, providers of existing REST(-like) APIs need to implement additional GraphQL interfaces to enable these advantages. We here assess the feasibility of automatically generating GraphQL wrappers for existing REST(-like) APIs. A wrapper, upon receiving GraphQL queries, translates them to requests against the target API. We discuss the challenges for creating such wrappers, including dealing with data sanitation, authentication, or handling nested queries. We furthermore present a prototypical implementation of OASGraph. OASGraph takes as input an OpenAPI Specification (OAS) describing an existing REST(-like) web API and generates a GraphQL wrapper for it. We evaluate OASGraph by running it, as well as an existing open source alternative, against 959 publicly available OAS. This experiment shows that OASGraph outperforms the existing alternative and is able to create a GraphQL wrapper for (89.5 ) of the APIs – however, with limitations in many cases. A subsequent analysis of errors and warnings produced by OASGraph shows that missing or ambiguous information in the assessed OAS hinders creating complete wrappers. Finally, we present a use case of the IBM Watson Language Translator API that shows that small changes to an OAS allow OASGraph to generate more idiomatic and more expressive GraphQL wrappers.
Previous work has attempted to automate the generation of REST(-like) API specifications, like OAS. One approach is to infer specifications from observed dynamic traces of a web server hosting an API @cite_3 . Another approach is infer specifications from proxied HTTP requests, which can be done by parties other than the provider of an API @cite_14 . While these works do not have the same goal of generating GraphQL wrappers, they help making specifications more broadly available and thus complement the here presented work.
@cite_14 @cite_3
2243050748 2554251271
RESTful API documentation is expensive to produce and maintain due to the lack of reusable tools and automated solutions. Most RESTful APIs are documented manually and the API developers are responsible for keeping the documentation up to date as the API evolves making the process both costly and error-prone. In this paper we introduce a novel technique using an HTTP proxy server that can be used to automatically generate RESTful API documentation and demonstrate SpyREST, an example implementation of the proposed technique. SpyREST uses a proxy to intercept example API calls and intelligently produces API documentation for RESTful Web APIs by processing the request and response data. Using the proposed HTTP proxy server based technique, RESTful API developers can significantly reduce the cost of producing and maintaining API documentation by replacing a large manual process with an automated process. We describe a set of techniques to infer structured descriptions of web APIs from usage examples. Using trained classifiers, we identify fixed and variable segments in paths, and tag parameters according to their types. We implemented our techniques and evaluated their precision on 10 APIs for which we obtained: 1) descriptions, manually written by the API maintainers, and 2) server logs of the API usage. Our experiments show that our system is able to reconstruct the structure of both simple and complex web API descriptions, outperforming an existing tool with similar goals. Finally, we assess the impact of noise in the input data on the results of our method.