/openapi-to-graphql

Translate APIs described by OpenAPI Specifications (OAS) into GraphQL

Primary LanguageTypeScriptMIT LicenseMIT

GitHub last commit Join the chat at https://gitter.im/IBM/openapi-to-graphql

OpenAPI-to-GraphQL

Translate APIs described by OpenAPI Specifications (OAS) or Swagger into GraphQL.

Overview of translation

Getting started

OpenAPI-to-GraphQL can be used in two ways:

CLI

The Command Line Interface (CLI) provides a convenient way to start a GraphQL server wrapping an API for a given OpenAPI Specification:

  1. Install the OpenAPI-to-GraphQL CLI using:
    npm i -g openapi-to-graphql-cli
  2. Then, run the OpenAPI-to-GraphQL command and point it to an OpenAPI Specification:
    openapi-to-graphql <OAS JSON file path or remote url> [options]

For further details, refer to the openapi-to-graphql-cli documentation.

Library

Use OpenAPI-to-GraphQL as a library in your application to generate GraphQL schemas.

  1. Install OpenAPI-to-GraphQL as a dependency:
    npm i -s openapi-to-graphql
  2. Require OpenAPI-to-GraphQL and use the createGraphQLSchema function:
    const { createGraphQLSchema } = require("openapi-to-graphql");
    // load or construct OAS (const oas = ...)
    const { schema, report } = await createGraphQLSchema(oas);

For further details, refer to the openapi-to-graphql documentation.

Tutorials

Here are some guides to further help you get started:

  • CLI + Loopback tutorial: Learn how to quickly spin up GraphQL wrappers using the OpenAPI-to-GraphQL CLI.
  • Library tutorial: Learn how to use OpenAPI-to-GraphQL as a library, and how to improve the resulting GraphQL wrappers using OAS link definitions.
  • LoopBack tutorial: Learn how to use OpenAPI-to-GraphQL to create GraphQL wrappers for APIs created with LoopBack 4.
  • Subscriptions tutorial: Learn how to create a GraphQL API that supports subscription operations - including how to set up the API server that creates a PubSub instance wrapping a MQTT client.

Characteristics

  • Data-centric The GraphQL interface is created around the data definitions in the given OAS, not around the endpoints, leading to a natural use of GraphQL.

    Example of data-centric design
  • Nested data Links defined in the OAS are used to create nested data structures, allowing for (deeply) nested queries.

    Example of links resolution
  • Automatic query resolution Automatically generated resolvers translate (nested) GraphQL queries to API requests. Request results are translated back to GraphQL responses.

    Example of query resolution
  • Mutations Non-safe, non-idempotent API operations (e.g., POST, PUT, DELETE) are translated to GraphQL mutations. Input payload is type-checked.

    Example of mutation
  • Subscriptions GraphQL subscriptions allow clients to receive a stream of events, such as updates whenever data changes on the GraphQL server. OpenAPI-to-GraphQL can create subscriptions based on callback objects defined in the OAS.

    Example of subscription
  • Authentication OpenAPI-to-GraphQL currently supports authentication via API Key and basic auth. OpenAPI-to-GraphQL wraps secured endpoints into a viewer, which takes the API key / credentials as input.

    Example of authentication
  • API Sanitation Parts of an API that not compatible with GraphQL are automatically sanitized. For example, API parameters and data definition names with unsupported characters (e.g., -, ., ,, :, ;...) are removed. GraphQL queries are desanitized to correctly invoke the REST API and the responses are resanitized to create GraphQL-compliant results.

    Example of sanitation
  • Custom request options Provide headers and query parameters to send with every API request. This allows, for example, to handle authentication or tag requests from GraphQL.

  • Swagger and OpenAPI 3 support OpenAPI-to-GraphQL can handle both Swagger (OpenAPI specification 2.0) as well as OpenAPI specification 3.

Development

OpenAPI-to-GraphQL is written in TypeScript. Within each of OpenAPI-to-GraphQL's packages, all source code is contained in the src folder. Use yarn build or yarn test to transpile the source files into the final library in the dist folder. Entry-point for the library is index.js in dist.

Research

Our research paper, "Generating GraphQL-Wrappers for REST(-like) APIs", can be found here. The paper describes the challenges of building OpenAPI-to-GraphQL and an experiment in which we evaluated OpenAPI-to-GraphQL against 959 publicly available OAS, provided by APIs.guru, and successfully created GraphQL interfaces for 89.5% of them.

To run the experiment, in the openapi-to-graphql package, load APIs.guru specifications, found here, into the /tmp folder:

npm run guru-load

Then, run tests:

npm run guru-test <number of APIs to test at most>

Similar projects

  • swagger-to-graphql turns a given Swagger (OpenAPI Specification 2.0) into a GraphQL interface, which resolves against the original API. GraphQL schema is based on endpoints, not on data definitions. No links are considered.

  • json-to-graphql turns given JSON objects / arrays into a GraphQL schema. resolve functions need to be provided by the user.

  • StackOverflow discussion points to the above projects.

License

MIT