メインコンテンツまでスキップ

バージョニング

CAFE24 APIは 日付ベースのバージョン（yyyy-mm-dd） で管理されています。 後方互換性のない変更（Breaking Changes）が発生したタイミングで新しい日付バージョンがリリースされ、呼び出し時に使用するバージョンを明示的に指定できます。

📌 バージョンフォーマット​

Version yyyy-mm-dd

例）2021-03-01、2024-09-01

後方互換性のない変更が発生するたびに、その時点の日付で新しいバージョンがリリースされます。

🔧 バージョンの指定方法​

リクエスト時に X-Cafe24-Api-Version カスタムヘッダーを指定することで利用するバージョンを選択できます。

curl -X GET \
  'https://{mallid}.cafe24api.com/api/v2/admin/products' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'X-Cafe24-Api-Version: yyyy-mm-dd'

ヘッダー未指定時の動作​

X-Cafe24-Api-Version ヘッダーを指定しない場合は、デベロッパーセンター > 開発情報に設定されているアプリのバージョン で動作します。

⚙️ アプリバージョンの設定経路​

アプリのバージョンはデベロッパーセンターで直接確認・変更できます。

デベロッパーセンター（ログイン） > Apps > 開発情報 > 認証情報内のバージョン管理
手順場所
1デベロッパーセンター にログイン
2Apps メニューを開く
3対象アプリの 開発情報 を選択
4認証情報 > バージョン管理 からバージョンを変更

⏳ バージョン有効期限ポリシー​

項目ポリシー
有効期間最新バージョンのリリース時点から 最大1年
失効後の動作失効していないバージョンのうち、最も古いバージョン に自動的に置き換え

⚠️ 利用中のバージョンが失効すると動作が変わる可能性があるため、新バージョンがリリースされたら互換性を確認し、明示的にアップグレードすることを推奨します。

🌐 適用範囲​

X-Cafe24-Api-Version ヘッダーは以下のAPI全般に同様に適用されます。

  • Admin API — 管理者向けREST API
  • Front API — フロントエンド向けREST API
  • Cafe24 Analytics API — 分析用API

3つのAPIすべてが同一の日付ベースバージョン体系および1年の有効期限ポリシーに従います。

💡 ベストプラクティス​

1. 本番環境ではバージョンを明示的に指定する​

# ✅ 推奨: バージョンを明示して予測可能な動作を保証
curl -X GET 'https://{mallid}.cafe24api.com/api/v2/admin/products' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'X-Cafe24-Api-Version: 2024-09-01'

バージョンを明示的に指定すれば、デベロッパーセンターのアプリバージョン設定が変更されても呼び出し動作に影響を受けません。

2. 新バージョンリリース時に互換性を確認する​

  • 新しい日付バージョンがリリースされたら変更点（Breaking Changes）を確認してください。
  • ステージング環境で新バージョンをテストしたうえで本番に反映します。

3. 失効間近バージョンのモニタリング​

  • 利用中のバージョンが1年の有効期限に近づいたら、事前にアップグレードを進めてください。
  • 失効したバージョンは自動的に別のバージョンに置き換わり、意図しない動作が発生する可能性があります。

📚 参考資料​