TechPrufer
Get started
Shopify
Shopify logoShopify · Feature trail

API Versioning and Breaking Change Management

1 post · Mar 2012 – Jun 2021

What this trail covers

Shopify has established a robust API versioning strategy to ensure stability and predictability for its partners. This involves releasing new API versions quarterly with date-based names (e.g., 2020-01). The platform team builds the infrastructure and tooling to enforce this strategy, which includes managing breaking and non-breaking changes. Breaking changes require thorough impact analysis and stakeholder agreement, while non-breaking changes are tested for forward compatibility. This post discusses the challenges of applying RESTful thinking to processes, advocating for transaction-specific URIs (e.g., POST /orders/42/pay) over generic updates (PATCH /orders/42) to improve clarity, authorization, and validation. It emphasizes modeling processes as state machines and avoiding direct `update_attributes` calls in controllers to enhance security and prevent mass-assignment vulnerabilities.

All Shopify trails
  1. Rate Limiting GraphQL APIs by Calculating Query Complexity - ShopifyThis post introduces a new rate limiting strategy for Shopify's GraphQL Admin API that moves beyond traditional request-based methods. It details a 'calculated query cost' method where each GraphQL request is assigned a cost based on the types and data it requests. Objects are 1 point, scalars/enums are 0 points, connections cost 2 points plus the number of returned objects, interfaces/unions are 1 point, and mutations are 10 points. The API response includes the calculated query cost in an extension object, and detailed per-field costs can be obtained with a specific header. The post also highlights the difference between requested and actual query costs, with refunds for unused costs, and demonstrates a linear correlation between calculated query complexity and execution time, enabling better infrastructure scaling and predictability.
  2. How Shopify Manages API Versioning and Breaking Changes - ShopifyThis post details Shopify's API versioning strategy, which releases new date-based API versions quarterly. It explains the distinction between breaking and non-breaking changes, the process for analyzing the impact of breaking changes using `mark_breaking` and `mark_possibly_breaking` methods, and how `ApiChange.in_effect?` is used to manage the rollout of changes. The analogy of retraining police dogs highlights the significant effort required for system-wide changes.
  3. RESTful thinking considered harmful - ShopifyThis post critiques the application of RESTful principles, specifically CRUD and HTTP methods like PUT/PATCH, to transactional processes in web applications. It argues that for process-related data (e.g., order payment, shipping), distinct URIs for each transaction (e.g., POST /orders/42/pay) are clearer and more secure than generic updates. It highlights the importance of modeling processes as state machines and ensuring that transaction-specific methods in models handle data updates, rather than relying on generic controller actions like `update_attributes` to prevent mass-assignment vulnerabilities.