adding-api-versions
Use when adding a new API version to the shopify-api package, creating REST resource files for a new version, updating API version constants, or handling breaking changes like removed or modified resources between versions.
来源信息
- 仓库
- Shopify/shopify-app-js
- 最近来源活动
- 2026年4月1日 14:36
- 检测到的 SKILL.md 语言
- 英语
- 星标
- 543
- 分支
- 229
安装方式
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
检查来源文件
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
正在显示 SKILL.md
SKILL.md
来源说明 · 只读预览- name
- adding-api-versions
- description
- Use when adding a new API version to the shopify-api package, creating REST resource files for a new version, updating API version constants, or handling breaking changes like removed or modified resources between versions.
# Adding a New API Version
Step-by-step process for adding a new API version to `packages/apps/shopify-api`. Uses 2025-07 as a reference example.
## Prerequisites
- Know which resources are removed or modified in the new version
## Step 1: Update API Version Constants
Edit `packages/apps/shopify-api/lib/types.ts`:
```typescript
export enum ApiVersion {
// ... existing versions ...
April25 = '2025-04',
July25 = '2025-07', // New version
October25 = '2025-10', // Release candidate (next version)
}
```
**Naming convention:** `{Month}{YY}` (e.g., `April25`, `July25`). Value format: `YYYY-MM`.
Also add the **next** quarterly version as a release candidate enum value (no REST resources needed yet).
## Step 2: Create Directory Structure
```bash
mkdir packages/apps/shopify-api/rest/admin/{YYYY-MM}/
mkdir packages/apps/shopify-api/rest/admin/__tests__/{YYYY-MM}/
```
## Step 3: Copy and Update Resource Files
Copy from the most recent version:
```bash
cp -r packages/apps/shopify-api/rest/admin/{PREVIOUS_VERSION}/* \
packages/apps/shopify-api/rest/admin/{NEW_VERSION}/
cp -r packages/apps/shopify-api/rest/admin/__tests__/{PREVIOUS_VERSION}/* \
packages/apps/shopify-api/rest/admin/__tests__/{NEW_VERSION}/
```
In every resource file, update the `apiVersion` property:
```typescript
// From
public static apiVersion = ApiVersion.April25;
// To
public static apiVersion = ApiVersion.July25;
```
## Step 4: Update Test Files
Two changes in every test file:
1. **testConfig calls:**
```typescript
testConfig({apiVersion: ApiVersion.July25, restResources})
```
2. **URL paths in expectations:**
```typescript
`https://test-shop.myshopify.com/admin/api/2025-07/...`
```
## Step 5: Update Index File
Edit `packages/apps/shopify-api/rest/admin/{NEW_VERSION}/index.ts`:
- Import all resources (except removed ones)
- Update `RestResources` interface
- Update `restResources` export
For removed resources, delete their imports and exports:
```typescript
// Remove from interface and export
export interface RestResources extends ShopifyRestResources {
// CustomerAddress: typeof CustomerAddress; // Removed in 2025-07
}
```
## Step 6: Handle Breaking Changes
For **removed resources** (e.g., CustomerAddress in 2025-07):
1. Delete the resource file from `rest/admin/{NEW_VERSION}/`
2. Delete the test file from `rest/admin/__tests__/{NEW_VERSION}/`
3. Remove imports/exports from `index.ts`
For **modified resources**:
1. Update class properties
2. Modify `paths` array if endpoints changed
3. Update method signatures if parameters changed
4. Adjust tests accordingly
## Step 7: Run Tests and Build
```bash
# Test the new version
pnpm test -- packages/apps/shopify-api/rest/admin/__tests__/{NEW_VERSION}
# Run all tests
pnpm test
```
## Checklist
- [ ] New enum value in `ApiVersion` (`packages/apps/shopify-api/lib/types.ts`)
- [ ] Next quarterly release candidate enum value added (no REST resources needed)
- [ ] Source directory created: `rest/admin/{NEW_VERSION}/`
- [ ] Test directory created: `rest/admin/__tests__/{NEW_VERSION}/`
- [ ] All resource files copied and `apiVersion` updated
- [ ] All test files updated (testConfig + URL paths)
- [ ] `index.ts` updated with correct imports/exports
- [ ] Removed resources and their tests deleted
- [ ] Modified resources updated
- [ ] All tests pass
- [ ] Package builds without errors
在 GitHub 查看