---
title: "Unifying Our GraphQL Design Patterns and Best Practices with Tutorials"
description: "Shopify describes how its GraphQL work grew from an early experiment for mobile APIs into contributions from hundreds of developers across teams and offices, including the Admin and Storefront APIs. As adoption expanded, sparse Markdown guidance left context inconsistently shared, while design guidelines were mixed with code-reference documentation and became difficult to extend for complex cases. The API Patterns Team, created in May 2017, addressed this by focusing on horizontal concerns, identifying common patterns, and documenting solutions for developers working across API domains. This work produced a living, in-depth design tutorial that explains Shopify’s GraphQL design philosophy through a practical example; its central rule is to understand the business domain and design the API to reflect it rather than the application’s implementation."
---

# Unifying Our GraphQL Design Patterns and Best Practices with Tutorials

[Shopify](https://yomu.fyi/company/shopify) · 2023-10-18 · Feb 13, 2019

**Type:** Tutorial

## Summary

Shopify describes how its GraphQL work grew from an early experiment for mobile APIs into contributions from hundreds of developers across teams and offices, including the Admin and Storefront APIs. As adoption expanded, sparse Markdown guidance left context inconsistently shared, while design guidelines were mixed with code-reference documentation and became difficult to extend for complex cases. The API Patterns Team, created in May 2017, addressed this by focusing on horizontal concerns, identifying common patterns, and documenting solutions for developers working across API domains. This work produced a living, in-depth design tutorial that explains Shopify’s GraphQL design philosophy through a practical example; its central rule is to understand the business domain and design the API to reflect it rather than the application’s implementation.

## Context

As Shopify’s GraphQL contributors expanded across teams and offices, limited documentation caused context to be missed and information to be shared inconsistently. Existing guidance also combined design guidelines with code-reference documentation, making complex patterns difficult to document and reuse.

## Approach / What changed

The API Patterns Team focused on horizontal concerns across the company, identifying common GraphQL patterns and documenting solutions. This work became a living, in-depth design tutorial that presents Shopify’s API design philosophy and practical applications through a real example.

## Takeaways

- Shopify’s GraphQL documentation began as sparse Markdown files and a bullet-point style guide before expanding into separate topic documents.
- The API Patterns Team was created in May 2017 to address API concerns spanning business domains and support developers beyond the two main public APIs.
- The tutorial’s fundamental rule is to understand the business domain and design the API around it rather than around the application’s implementation.

**Tags:** [Architecture](https://yomu.fyi/topic/architecture), [GraphQL](https://yomu.fyi/topic/graphql)

- Source: [Shopify](https://shopify.engineering/unifying-graphql-design-patterns-best-practices-tutorials)
- Source URL: https://shopify.engineering/unifying-graphql-design-patterns-best-practices-tutorials
- Ingested by Yomu: 2026-08-31T04:01:02.193Z

[Read original post](https://shopify.engineering/unifying-graphql-design-patterns-best-practices-tutorials)