GraphQL API implementation and teamwork

How we collaborate to implement our GraphQL API.

Developers are still human and need to interact with each other to deliver complex solutions.

GraphQL introduces a new layer to API implementation projects: the schema.

We can already find schemas in a lot of places: databases, JSON, XML documents and directories. GraphQL now brings this concept to our APIs, with endpoints turned into an extensible graph.

The GraphQL schema is also a hub of exchange and friction between API developers and their front-end counterparts.

Editor role

GraphQL is user-oriented, so the schema must be intuitive and provide straightforward solutions for developer integration cases. That’s why our GraphQL API implementation and our React Native mobile app development are in parallel. Queries and mutations are reviewed and tested with real scenarios. This makes communication easier while accelerating the decision-making process.

The first question that pops up is “Who is the owner of the schema?”

To keep the GraphQL schema consistent regarding type definitions, naming, and style, we have defined an editor role who is the “keymaster.”
From the vantage point of a global view, the editor ensures that the GraphQL schema serves front-end developers’ needs without being too specific to a business case. Indeed, the GraphQL schema will have to address more use cases that we can already anticipate. The editor has to take into consideration back-end constraints regarding complexity in the development and performance.

The editor has to preserve the product DNA in the GraphQL schema.

Our WorkflowGen API relies on an existing product with its own logic and history. The GraphQL API must reflect current realities in order to make development fluid; it’s not yet time to introduce new concepts or features if we want to expose, in the short term, the existing product functionalities in GraphQL.

The editor role also helps to balance the efforts between front-end and back-end developers, who can focus on their development and address schema-related issues with the editor.

Productivity and communication tools

To make teamwork easier, we are using a Slack channel to manage discussions about the GraphQL schema.

A good example of usage concerns naming, which has to be consistent across all types (and with the product UI, if relevant). Many exchanges in Slack are about the naming of types and fields, since this is important to make our API intuitive and precise, and to avoid confusion. GitHub issues are used during implementation.

We also use Postman to share collections of queries and mutations between front-end and back-end developer teams. Indeed, all developers need to know which queries are used in front-end apps.

Developers can anticipate breaking changes, query performance issues, and schema optimizations to do.

We also use the mocks feature provided by the excellent graph-tools library. By creating mocks instantly, a React Native developer team can code without having to wait for back-end deliveries, which translates into significant gains in productivity.

Schema definition file management

Even in alpha version, our GraphQL schema is big, and its size will double in future releases. As such, having a single file for type definitions and resolvers is not a viable option for us.

The GraphQL definition language is used to create type definition files (a feature provided by the graph-tools library). It’s a great solution to improve readability and maintainability.

The GraphQL schema has been split into multiple files that group the types by category (actions.js, requests.js, user.js and so on). This granularity makes teamwork smoother when working on the schema in parallel. It is also easier to edit existing types, queries or mutations. We apply the same principles to resolver and mocks files.

Type definition files and resolver files are loaded dynamically when the Node.js application starts.

// Load type definitions
  const typeDefs = [];
  fs.readdirSync(path.join(__dirname, 'typedefs'))
    .forEach(file => typeDefs.push(require('./typedefs/' + file)));
// Load resolvers
  var resolvers = {};
  fs.readdirSync(path.join(__dirname, 'resolvers'))
    .forEach(file => {
      const functions = require('./resolvers/' + file);
      merge(resolvers, functions);
    });
// Creates the schema
  const schema = makeExecutableSchema({
    typeDefs: typeDefs,
    resolvers: resolvers
  });

For new types or resolvers, we only have to create new .js files in the corresponding folders. No additional calls to import or require instructions are needed. This solution is also useful for our clients who want to extend the schema with their own types or resolvers.

Conclusion

A GraphQL API is a language that lets you interact with your product. The schema is a dialect you create for your API users to query your data and perform changes via mutations.

The GraphQL schema plays a significant role for development and support teams’ activities because all of the new features and customer integrations will depend on it, so it will probably impact business performance itself.

The schema is not static, though; type additions or deprecations will change its structure over time.

Your GraphQL schema must have some adaptability qualities to stand the test of time.

Finally, a GraphQL API implementation project requires a new level of exchange between the different actors, along with new responsibilities.
GraphQL opens new ways to manage modern application development such as “GraphQL first”, as introduced in this excellent post by Matt DeBergalis of the Meteor Development Group.