Unifying Our GraphQL Design Patterns and Best Practices with Tutorials

In 2015, Shopify began a journey to put mobile first. The biggest undertaking was rebuilding our native Shopify Mobile app and improving the tools and technology to accomplish this. We experimented with GraphQL to build the next generation of APIs that power our mobile apps and give our 800,000+ merchants the same seamless experience when using Shopify. There are currently hundreds Shopify developers across teams and offices contributing to our GraphQL APIs including our two public APIs: Admin and Storefront.

Background

Shopify started using GraphQL very early on after Facebook publicly released it. Since GraphQL was a brand new technology, there were no existing design guidelines or best practices to follow or even a community around it to discuss it. As early adopters, we had to face these issues head-on and come up with solutions to combat it. This meant discussing it with each other and creating our own guidelines and best practices.

With only a small group of people working on GraphQL at Shopify, we didn’t have much documentation. Not because we didn’t want to, but it’s often too early to formalize design guidelines and best practices when you’re still trying to figure them out as well. It’s difficult to identify common themes and solutions until you run into the same problem a few times with different use cases.

Finding a Solution to the Problem

As the number of people contributing to our GraphQL APIs grew, we quickly ran into scaling issues. Without much documentation around it, context was being missed and information wasn’t being shared consistently. So, we needed to start the documentation process before it became an even bigger problem. Like most documentation efforts, ours started very informally with some sparse Markdown documents in a GitHub repository. One of those being a style guide only consisting of bullet points. Over time, we slowly started expanding on those points and extracting topics into their separate files. However, this was often a mix of design guidelines and code reference documentation.

This mix was good enough for a while, but it was hard to document more complex design guidelines. We needed something more standalone that could be used by all developers at Shopify even if they were working on their API outside of our main two public ones. This was one of the reasons why the API Patterns Team was created back in May 2017. Since many developers who contribute to our APIs focus on their “vertical” features and business domains, we needed a team who focused on “horizontal” concerns across the entire company. The horizontal focus allows us to have API and company-wide context and identify common patterns and document our solutions for them.

Eventually, this work led us to create an in-depth design tutorial unifying Shopify's GraphQL design patterns and best practices. Our tutorial is a living document and is updated as we continue to iterate and improve it. If you have a basic knowledge of GraphQL, this tutorial is for you. It will walk you through our GraphQL API design philosophy from a high level while showcasing its practical applications through a real example. The major lesson we wanted to share with Shopifolk is to focus on understanding the business domain and ensure the API is designed to reflect that and not the application's implementation. These tutorials provide a reference on how to tackle this thinking and spread it across the organization. Focusing on the business domain is the API Patterns team most fundamental rule.

Interested in learning more about our GraphQL API? Then feel free to check out our full tutorial. 

We're always on the lookout for talent and we’d love to hear from you. Please take a look at our open positions on the Engineering career page.