A lot of companies are in the situation where they have a working, tested REST API server and they want to enable GraphQL queries as easily as possible.
Both are data access methods that allow end-users and developers to query and optionally update data hosted by a server. Note that there is an “impedance mismatch” between REST and GraphQL, since GraphQL can be considered a higher-level access method with pre-aggregated and pre-joined results with a single network request.
There’s 3 important object type concepts in GraphQL:
- Schema (in this case from api spec file)
- Query (read-only, which in many use cases is adequate alone)
- Mutation (optional updates or complex operations)
To import an OpenAPI spec file, it needs the following:
- 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.)
- 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:
{“users”:[{"first":"John”,”id":1000001,"last”:”Doe”}]}
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 {
name
}
}
}
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:
- start with a couple of read-only (GET) endpoints to become resolvers. (Read-only may suffice.)
- then try a couple of updates (POST/PUT/DELETE) (mutations) if needed.
Some GraphQL advantages are reducing aggregating REST API output, and reducing network requests. To obtain that benefit from your existing REST API server when using a GraphQL-REST API gateway, you may need to add additional REST API endpoints for common complex GraphQL requests. For example, perhaps doing a SQL JOIN behind the scenes and returning that result in one request. An example is that if there’s Employees and Companies tables, then you may want a GraphQL query to return joined table data with employee name and company name without two REST API calls.
GraphQL: Building a consistent approach for the API consumer
OpenAPI Specification
GraphQL vs. REST: A Comprehensive Comparison
