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.

For 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.

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
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

1// ./src/index.ts
2import schema from './schema';
4// This is how you need to handle unix socket addresses with superagent it's ugly I know but it works!
5const baseURL = 'http+unix://%2Fvar%2Frun%2Fdocker.sock';
6const config = {
7 port: 3000,
8 schema, // We'll come to that in the next part :)
9 context: ({ req }) => {
10 return {
11 baseURL,
12 };
13 },
16const server = new ApolloServer({
17 schema,
18 context,
21server.listen(port).then(({ url }) => {
22 console.log(`Server ready at ${url}`);

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

1// ./src/schema/service/typeDefs.ts
3import { gql } from 'apollo-server';
5const typeDefs = gql`
6 extend type Query {
7 services: [Service!]!
8 service(id: ID!): Service!
9 }
11 type ServiceSpecType {
12 Name: String!
13 Mode: ServiceMode
14 }
16 type ServiceMode {
17 Replicated: ServiceReplicated
18 }
20 type ServiceReplicated {
21 Replicated: Int!
22 }
24 type Service {
25 ID: ID!
26 CreatedAt: String!
27 UpdatedAt: String!
28 Spec: ServiceSpecType!
29 containers: [Container!]!
30 }
33export default typeDefs;

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

1// ./src/schemas/container/typeDefs.ts
3import { gql } from 'apollo-server';
5const typeDefs = gql`
6 extend type Query {
7 container(id: ID!): Container!
8 }
10 type Container {
11 Id: String!
12 Command: String!
13 Image: String!
14 MountLabel: String
15 Names: [String!]!
16 State: String!
17 Status: String!
18 }
21export default typeDefs;

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

1// ./src/schema/service/resolvers/index.ts
3import request from 'superagent';
4import Service from './Service';
7Resolvers take 3 arguments:
8- parent: an object which is the result returned by the resolver on the parent field.
9- args: an object that contains the arguments passed to the field. In our example below, id is an argument for service.
10- context: the object that we passed to our GraphQL server. In our case context contains the baseURL field.
13const Query = {
14 services: async (_parent, _args, { baseURL, authorization }) => {
15 const { body } = await request.get(`${baseURL}/services`);
16 return body;
17 },
18 service: async (_parent, args, { baseURL, authorization }) => {
19 const { id } = args;
20 const { body } = await request.get(`${baseURL}/services/${id}`);
21 return body;
22 },
25export default { Query, Service };

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

1// ./src/schemas/service/resolvers/Service.ts
2import request from 'superagent';
4const Service = {
5 containers: async (parent, _args, { baseURL, authorization }) => {
6 const { ID } = parent;
7 const filters = {
8 label: [`${ID}`],
9 };
10 const { body } = await request.get(
11 `${baseURL}/containers/json?filters=${encodeURI(JSON.stringify(filters))}`
12 );
14 return body;
15 },
18export default Service;

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

1// ./src/schemas/index.ts
3import { makeExecutableSchema } from 'apollo-server';
4import merge from 'lodash/merge';
5import service from './service/resolvers';
6import serviceType from './service/typeDefs';
7import containerType from './container/typeDefs';
9const resolvers = merge(service, otherpotentialresolvers);
10// Type definitions, like Service can extend this Query type.
11const Query = gql`
12 type Query
15const global = [Query];
16const typeDefs = [, containerType, serviceType];
18const schema = makeExecutableSchema({
19 typeDefs,
20 resolvers,
23export default schema;

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

1query {
2 services {
3 ID
4 Spec {
5 Name
6 }
7 }

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:

Expected result from the sample GraphQL query above

2 "data": {
3 "services": [
4 {
5 "ID": "t5rwuns2x9sb6g16hlrvw03qa",
6 "Spec": {
7 "Name": "funny_rosalind"
8 }
9 }
10 ]
11 }

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

1query {
2 services {
3 ID
4 Spec {
5 Name
6 }
7 containers {
8 Names
9 }
10 }

which should output the following result:

The expected result from the sample GraphQL query above

2 "data": {
3 "services": [
4 {
5 "ID": "t5rwuns2x9sb6g16hlrvw03qa",
6 "Spec": {
7 "Name": "funny_rosalind"
8 },
9 "containers": [
10 {
11 "Names": ["/funny_rosalind.1.izqtpqtp52oadkdxk4mjr5o54h1"]
12 }
13 ]
14 }
15 ]
16 }

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


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

1# ./codegen.yml
2schema: src/schema/index.ts
3overwrite: true
4watch: false
6 - ts-node/register
8 ./src/types/types.d.ts:
9 config:
10 contextType: ./context#MyContext # this references the context type MyContext that is present in src/types/context.d.ts, more about it below
11 plugins:
12 - typescript-common
13 - typescript-server
14 - typescript-resolvers

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 .


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

1export type MyContext = {
2 baseURL: string;

Generating types

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

Generate type script in package.json

1"scripts": {
2 "generate-types": "gql-gen"

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 share it or click here to leave a comment discuss about it on Twitter. Do you have any questions, comments or simply wish to contact me privately? I’m always reachable on Twitter or on my website!

Have a wonderful day.

© 2019 Maxime Heckel. Made in SF.