OpenAPI to GraphQL Gateways

A lot of people are in the situation where they have a working, tested REST API server and they want to enable GraphQL queries as easily as possible.

There’s 3 important object type concepts in GraphQL:

  1. Schema (in this case from api spec file)
  2. Query (read-only, which in many use cases is adequate)
  3. Mutation (optional updates or complex operations)

To import an OpenAPI spec file, it needs the following:

  1. response schema fields for each endpoint. OpenAPI REST APIs usually don’t need this since JSON can be dumped directly, but it’s mandatory with GraphQL. (GraphQL IDEs, like Altair, use the schema info for autocompletion and pulldowns also.)
  2. compatibility with the gateway OpenAPI parser.

Here are some approaches from easiest to hardest/more expensive:

1. IBM’s OpenAPI to GraphQL gateway and library

Try this out first, but it has a lot of rough edges:

  • read the Issues and Pull Requests first
  • doesn’t parse multiple types per endpoint
  • in my case, auth worked but Altair didn’t show any response fields, possibly because of response envelopes.

Example of minor “enveloping” (the {“users”: part) that seems to confuse it:


Insert this line at the top of openapi-to-graphql:

#!/usr/bin/env node

Starting the listener (it’s a node.js application) on linux:

$ openapi-to-graphql api.yaml
GraphQL accessible at: http://localhost:3000/graphql

How to do schema introspection in Altair GraphQL client to see GraphQL resolvers (endpoints):

  __schema {
    types {

2. try a couple of lower-level libraries/frameworks

The challenges are installation errors from library dependencies, and more programming effort than using a gateway listener as in #1.

3. pay for a commercial gateway solution.

You will likely get a more polished solution with more technical support than the current Open Source solutions.

Some strategies for evaluating an OpenAPI to GraphQL gateway:

  1. start with a couple of read-only (GET) endpoints to become resolvers. (Read-only may suffice.)
  2. then try a couple of updates (POST/PUT/DELETE) (mutations) if needed.

GraphQL: Building a consistent approach for the API consumer
OpenAPI Specification

This entry was posted in API Programming, Business, Cloud, Linux, Open Source, Perl, REST API Programming, Tech. Bookmark the permalink.

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.