Nov 28, 2020
020: Building GraphQL Clients Over Existing APIs
This is a continuation of a series following along with my learning journey for GraphQL + Insomnia. Find the source code to follow along with here.
GraphQL
I’m at the point where I want to begin building out a GraphQL client. I thought I might be able to leverage existing GraphQL APIs to play with, but this continues to prove to be a challenge.
Entry points remain a problem. I’ve touched on this before. Most public GraphQL APIs I’ve come across seem to require that you already know specific data points in order to send and fulfill queries. Maybe I’m missing something, but as far as I can tell, much of what exists out in the wild is nigh unusable unless you already have information to get you started. Despite schema introspection and schema-generated documentation, there isn’t enough to make use of an existing GraphQL API without existing familiarity with the thing.
In Why We Don’t See Many Public GraphQL APIs, Marc-André Giroux makes a good point regarding GraphQL API docs:
With GraphQL, clients are in charge of defining their use cases, which can be both great and terrifying. … There are ways to make this better, which is by making sure documentation for a GraphQL API doesn’t stop after generating a big reference from the schema. Of course this is the case for any API, but GraphQL inherently makes discovering use cases a bit harder for clients, which means we have to be extra careful about it.
Documentation is something I’ve been on a tear about since I started working with libraries and APIs external to my projects. GraphQL seems to have the particular issue where because documentation can be generated from the schema, there is no further thought or effort put into fleshing out the documentation. Pull up a GraphQL playground and you’re given access to review the schema; you may have some docs to go with it; the docs however, if available, are typically not any more useful than the schema itself. This is a problem if you’re unfamiliar with the backend design and data of, say, GraphQL Jobs, for example. Perhaps this is due to my limited experience, but if I wanted to build an app that would query this API for jobs in a particular city, I have no idea what is expected of me in some of these fields to make that possible.
Not everything needs to be documented in detail. But at the very least, include a place to start. For the time being, it seems I’m better off finding public REST APIs and building my own schemas against those, on top of which I can build my client. This is the case for one of Ben Awad’s projects, in which he created types and resolvers to query data from the Star Wars API. I could also make a collection in MongoDB full of mocked data, or find a public database with freely accessible data, or create objects with mocked data over which to build the API.
Plenty of options, I suppose, and none of which include querying existing public GraphQL APIs.
Insomnia
I created a new workspace and created separate GET requests for the main categories in the Star Wars API. One thing I noticed recently is that you can pull the schema in JSON form for each entry type. Having access to this information will simplify creating a GraphQL schema, methinks. Tomorrow, .i begin the process of learning how to leverage TypeScript to manage types and look into processing .graphql files.
020/100
