shopify-api-rest

Shopify REST Admin API (DEPRECATED)

DEPRECATION NOTICE: The Shopify REST Admin API was deprecated in October 2024. All new development MUST use the GraphQL Admin API. This skill exists for maintaining legacy code and planning migration.

Before writing code

Fetch live docs:

1. Web-search site:shopify.dev rest admin api deprecation for deprecation timeline
2. Web-search site:shopify.dev migrate rest to graphql for migration guide
3. Fetch https://shopify.dev/docs/api/admin-rest for REST reference (if maintaining legacy code)

REST API Overview (Legacy)

Endpoints

• Base URL: https://{store}.myshopify.com/admin/api/{version}/
• Resources: products.json, orders.json, customers.json, etc.
• CRUD via HTTP methods: GET, POST, PUT, DELETE

Authentication

• Header: X-Shopify-Access-Token: {token}
• Same OAuth tokens work for both REST and GraphQL

Rate Limits

• Bucket-based: 40 requests per app per store (leaky bucket)
• Headers: X-Shopify-Shop-Api-Call-Limit: 32/40
• Plus stores: 80 requests

Pagination

• Cursor-based via Link header (not page numbers)
• rel="next" and rel="previous" links

REST-to-GraphQL Migration

Common Mappings

REST Endpoint	GraphQL Equivalent
GET /products.json	query { products(first: 50) { edges { node { ... } } } }
POST /products.json	mutation { productCreate(input: {...}) { ... } }
PUT /products/{id}.json	mutation { productUpdate(input: {...}) { ... } }
DELETE /products/{id}.json	mutation { productDelete(input: {id: "..."}) { ... } }
GET /orders.json	query { orders(first: 50) { edges { node { ... } } } }
GET /customers.json	query { customers(first: 50) { edges { node { ... } } } }

Key Differences

Aspect	REST	GraphQL
Data shape	Fixed response	Client-defined
Rate limiting	Request count (40/s)	Cost-based (1000 points)
Pagination	Link headers	Cursor arguments
Bulk operations	Not available	bulkOperationRunQuery
Webhooks	REST endpoint	Same (subscription via GraphQL)
ID format	Numeric (12345)	GID (gid://shopify/Product/12345)

ID Conversion

REST uses numeric IDs; GraphQL uses Global IDs (GIDs):

• REST: 12345
• GraphQL: gid://shopify/Product/12345
• Convert: prefix with gid://shopify/{ResourceType}/

Migration Strategy

1. Audit existing REST calls — list all endpoints and frequencies
2. Map each REST call to its GraphQL equivalent
3. Migrate incrementally — replace one endpoint at a time
4. Leverage bulk operations — replace paginated REST loops with single bulk queries
5. Update error handling — GraphQL returns 200 with userErrors, not HTTP status codes
6. Test thoroughly — responses have different shapes

Best Practices

• Do NOT write new code against the REST API
• Prioritize migrating high-frequency REST calls first
• Use bulk operations to replace REST pagination loops
• Update ID handling from numeric to GID format
• Test migration against a development store

Fetch the Shopify REST-to-GraphQL migration guide for exact endpoint mappings and timeline before planning a migration.