orcaqubits/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.