Building a GraphQL wrapper for the Docker API

From REST calls to powerful queries

Maxime Heckel
May 28, 2019 · 9 min read

A more accessible, readable, mobile-friendly and up to date version of this story is available on my personal blog!

Note: the content of this post and the code featured in it have been produced on my own personal time and does not reflect my current work being done at Docker.

or the past 6 years, I have been working with the Docker API almost on a daily basis, whether it’s been in the context of personal projects, or when building products at Docker. However, since I started building UIs for container management software, I’ve always struggled with how to know how the different Docker objects are related. This made building comprehensive and easy to use user interfaces challenging, especially because in order to get all the related resources orbiting around a service or a container, for example, we always ended up doing quite a few REST API calls, manipulating filters, and “over fetching” to get the data we were interested in displaying.
These are exactly the problems that GraphQL is trying to solve and this is what this article will focus on: How to build a GraphQL wrapper around the Docker API.

Why?
I’ve never taken the time to get started seriously with GraphQL and I know the Docker API and how it could be better and easier to use. So, I thought this would be the perfect project to learn more about GraphQL, build something that matters and of course share with you about what I’ve learned.

What you will learn
In this post you will learn to:

  • Build a GraphQL server that wraps the Docker API
  • Build and organize resolvers and schemas
  • Running queries against our GraphQL server
  • Generate typescript types from the GraphQL schemas

If you want to follow along with this article with more details about the code I recommend checking out the project on Github. It’s based on apollo-server , typescript, graphql, lodash and superagent .

Setting up the server

The first step consists of being able to communicate with the Docker engine’s API through our GraphQL server. We want it to kind of act as a proxy between our client and Docker Engine, i.e. translate the GraphQL queries given by a client to rest calls, and send the results back. I recommend this article about such use of GraphQL, it’s written by Prisma, and it’s a great starting point for anyone who is not really familiar with GraphQL.

Illustration showcasing GraphQL as a layer between our client and the docker engine mapping queries to REST requests

Considering we have a Docker engine running locally, we can access the API through the Docker daemon which uses the UNIX socket unix:///var/run/docker.sock . Knowing that, we can start building the first pieces of our server:

Entrypoint of our GraphQL server

As we can see above, we’re setting up a new Apollo GraphQL server with two main components:

  • the context, which is an object we can define ourselves with fields that we will need in the future. Here we’re passing the UNIX socket address of the Docker daemon that we will use to contact the API when querying data.
  • the schema, the central and main piece of any GraphQL project. It will hold all the relationships between the different types and the different operations available to query our data (you can read more about it here). As it is the most important piece of our project, the next part will be dedicated to how to build our schema.

Building our schema

The schema we will need for our Docker API GraphQL wrapper is composed of two main parts:

  • typeDefs or type definitions. We will define how our Docker resources are architected and related to each other in our graph.
  • resolvers which are functions where each one of them is associated with a single field and will be used to fetch data from the Docker API.

To keep this article as accessible as possible and not too overwhelming, we will only focus on implementing typeDefs and resolvers for Docker services and containers. If you don’t know what a service or a container is, you can learn more about them at the following links:

These two resources are closely related: A service is composed of multiple containers. However, if you want to know which containers are within a given service, you have to do at least two REST API calls: one to get the service and one to get a filtered list of containers that compose that service.
We will see that thanks to the GraphQL wrapper we can have the same information with one single query, and with exactly the data we want (i.e. no over fetching).

Writing our type definitions

For services, most of the fields are mirroring what can be found in the Docker API documentation, however, you can see below that one extra field is present: containers. When we’ll add this field to a service query, we will get the containers within that service. We’ll define later a specific resolver for that field that will fetch the related containers of a given service.

Service type definitions

We can keep adding as many “custom fields” as we want if we feel that there’s a relationship between resources that needs to be reflected by the type definition. Here we’ll just focus on containers, since our aim is to be able to run a single query to get services with their related containers.

Container type definitions

Now that we have our typDefs we need to focus on the next part composing our schema:

Building our resolvers

Given that we’re focusing on services only, we’ll only write resolvers for service (other resources follow the same model and concepts).
The following code snippet is what can be called our “main resolver” and by that I mean that it’s the resolver that extends the main Query Resolver object. Below, we can see that we wrote two resolvers: one to fetch the services, i.e. the list of services, and another one service, to fetch a specific service by passing an ID. These two resolvers will call their corresponding REST endpoint in the Docker API if the field “services” or “service” are passed in a GraphQL query.

Query resolvers with the services and service fields

We can see that we’re also importing a Service resolver in the code above. This file will contain the resolvers for the fields that are extending our Service type definition. In our case, we’ll write a function that resolves the containers field.

Service resolver with the containers field

TypeDefs + Resolvers = Schemas

To get our Schemas we’ll need to use a function from apollo-server called makeExecutableSchema . This function will take our type definitions and resolvers and return our GraphQL schema:

The schema for our GraphQL server based on the typeDefs and resolvers we defined previously

We now have all the elements to start our GraphQL server. Considering we have Docker running, we can run the command: ts-node ./src/index.ts .
By going to http://localhost:3000 we should see the GraphiQL IDE that will allow us to run queries against our GraphQL server.

Running Queries

Let’s give a try to our server by running a GraphQL query against it. First, we’ll need to start a service on our local Docker engine to make sure we have some data. For that we can use the following command: docker service create nginx . This will create a small NGINX docker service.
When it is fully running, we can run the following query:

Sample GraphQL query that aims to fetch the list of services with their respective IDs and Names

This query will get us the services running on our Docker engine, with their IDs and Names. The server should output a response very similar to the following one:

The expected result from the sample GraphQL query above

We just ran our first GraphQL query to fetch the list of Docker services 🎉! Here we can see that we ran a query to get only some parts of the data available through the Docker API. This is one huge advantage of GraphQL, you can query only the data you need, no over-fetching!

Now let’s see how running a single query can get us both the list of services with their related containers. For that we’ll run the following query:

Sample GraphQL query that aims to fetch the list of services with their respective IDs and Names and related containers

which should output the following result:

The expected result from the sample GraphQL query above

It would typically take two REST calls to get that kind of data on a client, thanks to GraphQL and the way we architected our type definitions, it now only requires a single query!

Bonus: Typing our GraphQL server

You probably noticed that, since the beginning of this post, we’ve based our GraphQL server on Typescript. Although this is optional I wanted to showcase what can be achieved when building a GraphQL server with Typescript, and how we can leverage the schemas we’ve built to generate our Typescript types that can be used both on the server and on the client side.
To do so, we’ll need to install the following dependencies:

  • @types/graphql
  • graphql-code-generator
  • graphql-codegen-typescript-common
  • graphql-codegen-typescript-resolvers
  • graphql-codegen-typescript-server

Codegen.yml

The first thing we have to do after installing the required dependencies is to create a codegen.yml file at the root of our project that will serve as a configuration file for graphql-code-generator and fill it as follows:

Sample codegen configuration file for graphql-code-generator

Thanks to this configuration, graphql-code-generator will read our schemas located in src/schema/index.ts and output the generated types in src/types/types.d.ts .

ContextType

In our server implementation, we rely on a context to pass the baseURL to our resolver. This will require some typing that we’ll have to do manually. For that, we’ll need to create a types directory under ./src and within that directory a context.d.ts file that will contain the type of our context object, in our case just a baseURL field of type String:

Context object type declaration

Generating types

At this point, we just have to add the following script to our package.json:

Generate type script in package.json

and run yarn generate which should generate all the types for our query resolver, service resolver, service, container and any Docker resource type we may have added to our GraphQL server. These types can then be added to the resolvers or to any client that would query this GraphQL server.

Recapping and conclusion

In this post we learned how to:

  • set up a GraphQL server using apollo-server that wraps the Docker API.
  • write type definitions for Docker resource based on the API spec.
  • write resolvers
  • build a schema based on the resolvers and the type definitions
  • generate Typescript types based on the schema

These were my first steps with GraphQL and I hope my work will inspire others to build great projects with what they learned through this post. The code featured in this article can be found here. I plan on continuing to build this project in my spare time. I added contributing guidelines and a quick roadmap for anyone willing to participate in this project.
If, like me a few months ago, you’re getting started right now with GraphQL, or looking to learn more about it, here are the several links that I found more than useful:


If you liked this article don’t forget to hit the “clap” button and if you have any other questions I’m always reachable on Twitter, or on my website. You can also subscribe to my Medium publication to not miss my next post.

Have a wonderful day.
Maxime

Maxime Heckel

Software engineer and space enthusiast. Currently working for @docker.

Thanks to Christina Guo

Maxime Heckel

Written by

Software engineer and space enthusiast. Currently working for @docker.

Maxime Heckel

Software engineer and space enthusiast. Currently working for @docker.

More From Medium

More from Maxime Heckel

More from Maxime Heckel

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade