Using a GraphQL schema to supercharge team collaboration

Decoration computer

How we use a GraphQL schema to dramatically simplify syncing between back-end and front-end.

A single source of truth for app data

Ropig is built with GraphQL. There are plenty of goodies GraphQL has to offer, but in this post, I want to go over one of our favorites: the schema.

A GraphQL schema describes your data. Using GraphQL’s fantastic type system, you can clearly define the public API of your entire back-end. It looks like this:

This means that with a schema you have a single contract between the back-end and front-end.

With just this simple schema, we know exactly what we can do with our app’s API. For example, we can:

  • run registerUser on new user signup
  • run logout to log the user out
  • run login to log the user in
  • run updateBilling to let the user subscribe using a credit card
  • query billing to see what plan the user is on

This type of contract on top of a solid type system opens up some sweet possibilities…

Abstracting implementation

With a schema, we know what our public contract is for our API. It doesn’t matter if updateBilling is using Stripe or Paypal under the hood for payment processing, or if the back-end language is Elixir or Java, or if user data is being stored in PostgreSQL or MongoDB. We have a clean public API and can change the implementation details on back-end or front-end without breaking the rest of the system.

Working in tandem

A schema also lets you work quickly across the stack. For example, let’s say we now want to add a feature where we can show an entire team (every user in a company). The front-end or back-end could propose some schema changes like:

And now both the back-end and front-end can proceed with their implementations without holding each other back. Then, when implementations are ready, it should “just work” as long as the schema is respected. We have been doing this on Ropig for a long time and this workflow has truly just worked for us most of the time.

Generating the schema from the API

Instead of maintaining the schema file manually, you can have it automatically generated by your API. There are a few ways you can do this, but I recommend using graphql-config and graphql-cli. Then you can use a .graphqlconfig like:

Next, just run graphql get-schema to update your schema.graphql file with the latest changes in the API.

Generating types for other type systems from the schema

Having a schema lets you automate other things from the type system as well. For example, you can generate types for other type systems from it (for TypeScript, Flow, Swift, Scala etc.) using something like apollo-codegen. For example, Ropig uses Flow so we can run:

apollo-codegen generate **/*.graphql --target flow --output schema.flow.js

to generate Flow types automatically from schema types. It can use a .graphqlconfig to locate your schema just like we did in the previous section.

Generating example data from the schema

With a schema, you can automatically generate example data that can be used for building out the front-end before the real back-end is ready or for testing. The usage depends on what tools and languages you are using. For example, on Ropig we are using Apollo with React on the front-end, so we can use apollo-link-schema for this. We just pass it mock functions for certain schema types that look like this (in JavaScript, with faker for example):

Then the API is wrapped to use these mocked functions depending on the environment. So, for example, in a test or dev environment, we could get back example data to use in building out new features (before the real back-end is ready) or in tests!

Conclusion

GraphQL has a lot going for it. This is cool stuff. But especially having a schema as a public contract is very helpful. I bet we have just scratched the surface of what is possible. I’m excited about the future of GraphQL!

Trevor Miller
Trevor Miller
I'm a Software Engineer on the Ropig team. I love learning and solving problems. Being a programmer isn't just a job for me, it's a hobby too. I especially enjoy working in the terminal and contributing to open source. I strive to learn new things every day and share what I learn.

Send this to a friend