技能 编程开发 Flexport API版本升级与迁移指南

Flexport API版本升级与迁移指南

v20260423
flexport-upgrade-migration
本指南为开发者提供了从Flexport API v1到v2版本的详细迁移路径。内容涵盖了版本升级的关键变化,包括HTTP请求头、响应体结构(如_object到data)的解析方法、分页逻辑以及错误处理格式的更新,确保您的代码能够平稳过渡到新版本。
获取技能
436 次下载
概览

Flexport Upgrade & Migration

Overview

Guide for migrating between Flexport API versions. The main API uses Flexport-Version header (currently 2). The Logistics API has dated versions (2023-10, 2024-04). Breaking changes are versioned -- old versions remain available during deprecation windows.

Instructions

Step 1: Identify Current API Usage

# Find all Flexport API calls in your codebase
grep -rn "Flexport-Version\|api.flexport.com\|logistics-api.flexport.com" src/ --include="*.ts" --include="*.py"

# Check which version header you're sending
grep -rn "Flexport-Version" src/ --include="*.ts"

Step 2: API v1 to v2 Migration

Changev1v2
HeaderFlexport-Version: 1Flexport-Version: 2
Response wrapper{ "_object": "Shipment", ... }{ "data": { ... } }
Pagination{ "next": "/shipments?page=2" }{ "data": { "records": [], "total_count": N } }
Error format{ "errors": [...] }{ "error": { "code": "...", "message": "..." } }
Date formatMixedISO 8601 consistently
// v1 pattern (deprecated)
const res = await fetch(`${BASE}/shipments`, { headers: { 'Flexport-Version': '1' } });
const { _object, id, status } = await res.json();

// v2 pattern (current)
const res = await fetch(`${BASE}/shipments`, { headers: { 'Flexport-Version': '2' } });
const { data } = await res.json();
data.records.forEach(s => console.log(s.id, s.status));

Step 3: Logistics API Version Migration

// The Logistics API has separate versioned URLs
// Old: https://docs.logistics-api.flexport.com/2023-10/
// New: https://docs.logistics-api.flexport.com/2024-04/

// Check OpenAPI spec for changes
// https://logistics-api.flexport.com/logistics/api/2024-04/documentation/raw

Step 4: Dual-Version Testing

// Run both versions in parallel during migration
async function migrateEndpoint(path: string) {
  const [v1Res, v2Res] = await Promise.all([
    fetch(`${BASE}${path}`, { headers: { ...auth, 'Flexport-Version': '1' } }),
    fetch(`${BASE}${path}`, { headers: { ...auth, 'Flexport-Version': '2' } }),
  ]);

  const v1 = await v1Res.json();
  const v2 = await v2Res.json();

  // Compare key fields to verify migration correctness
  console.log('v1 count:', v1.total || 'N/A');
  console.log('v2 count:', v2.data?.total_count || 'N/A');
}

Migration Checklist

  • [ ] Update Flexport-Version header to 2
  • [ ] Update response parsing from _object to data.records
  • [ ] Update pagination logic for v2 format
  • [ ] Update error handling for v2 error format
  • [ ] Run test suite against v2 endpoints
  • [ ] Deploy to staging and verify
  • [ ] Monitor error rates after production deployment

Resources

Next Steps

For CI integration during upgrades, see flexport-ci-integration.

信息
分类 编程开发
名称 flexport-upgrade-migration
版本 v20260423
大小 3.45KB
更新时间 2026-04-26
语言