Building a GraphQL wrapper for the Docker API

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.

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:

1
// ./src/index.ts
2
import schema from './schema';
3

4
// This is how you need to handle unix socket addresses with superagent it's ugly I know but it works!
5
const baseURL = 'http+unix://%2Fvar%2Frun%2Fdocker.sock';
6
const config = {
7
  port: 3000,
8
  schema, // We'll come to that in the next part :)
9
  context: ({ req }) => {
10
    return {
11
      baseURL,
12
    };
13
  },
14
};
15

16
const server = new ApolloServer({
17
  schema,
18
  context,
19
});
20

21
server.listen(port).then(({ url }) => {
22
  console.log(`Server ready at ${url}`);
23
});

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.

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.

1
// ./src/schema/service/typeDefs.ts
2

3
import { gql } from 'apollo-server';
4

5
const typeDefs = gql`
6
  extend type Query {
7
    services: [Service!]!
8
    service(id: ID!): Service!
9
  }
10

11
  type ServiceSpecType {
12
    Name: String!
13
    Mode: ServiceMode
14
  }
15

16
  type ServiceMode {
17
    Replicated: ServiceReplicated
18
  }
19

20
  type ServiceReplicated {
21
    Replicated: Int!
22
  }
23

24
  type Service {
25
    ID: ID!
26
    CreatedAt: String!
27
    UpdatedAt: String!
28
    Spec: ServiceSpecType!
29
    containers: [Container!]!
30
  }
31
`;
32

33
export 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.

1
// ./src/schemas/container/typeDefs.ts
2

3
import { gql } from 'apollo-server';
4

5
const typeDefs = gql`
6
  extend type Query {
7
    container(id: ID!): Container!
8
  }
9

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
  }
19
`;
20

21
export 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.

1
// ./src/schema/service/resolvers/index.ts
2

3
import request from 'superagent';
4
import Service from './Service';
5

6
/* 
7
Resolvers 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.
11
*/
12

13
const 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
  },
23
};
24

25
export 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.

1
// ./src/schemas/service/resolvers/Service.ts
2
import request from 'superagent';
3

4
const Service = {
5
  containers: async (parent, _args, { baseURL, authorization }) => {
6
    const { ID } = parent;
7
    const filters = {
8
      label: [`com.docker.swarm.service.id=${ID}`],
9
    };
10
    const { body } = await request.get(
11
      `${baseURL}/containers/json?filters=${encodeURI(JSON.stringify(filters))}`
12
    );
13

14
    return body;
15
  },
16
};
17

18
export 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:

1
// ./src/schemas/index.ts
2

3
import { makeExecutableSchema } from 'apollo-server';
4
import merge from 'lodash/merge';
5
import service from './service/resolvers';
6
import serviceType from './service/typeDefs';
7
import containerType from './container/typeDefs';
8

9
const resolvers = merge(service, otherpotentialresolvers);
10
// Type definitions, like Service can extend this Query type.
11
const Query = gql`
12
  type Query
13
`;
14

15
const global = [Query];
16
const typeDefs = [...global, containerType, serviceType];
17

18
const schema = makeExecutableSchema({
19
  typeDefs,
20
  resolvers,
21
});
22

23
export 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:

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

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:

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

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:

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

which should output the following result:

1
{
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
  }
17
}

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:

1
# ./codegen.yml
2
schema: src/schema/index.ts
3
overwrite: true
4
watch: false
5
require:
6
  - ts-node/register
7
generates:
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 .

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:

1
export type MyContext = {
2
  baseURL: string;
3
};

Generating types

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

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

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:

• How to wrap a REST API with GraphQL - A 3-step tutorial | Prisma
• Lessons Learned Migrating APIs to GraphQL 📝
• Type-Safe GraphQL Servers 🔎