バージョニング

概要

BlueAI API は Stripe スタイルの日付ベースバージョニングを採用しています。すべてのエンドポイントは /api/v1/ プレフィックスで提供され、破壊的変更は BlueAI-Version ヘッダーで制御されます。

BlueAI-Version ヘッダー

リクエストに BlueAI-Version ヘッダーを含めることで、特定のバージョンの API 動作を指定できます。形式は YYYY-MM-DD です。

curl https://api.blueai.jp/api/v1/crm/deals \
  -H "BlueAI-Version: 2026-02-22" \
  -H "Authorization: Bearer sk_live_xxx"

バージョン解決順序

API バージョンは以下の優先順位で解決されます：

1. リクエストの BlueAI-Version ヘッダー（明示的に指定した場合）
2. 組織のデフォルトバージョン（metadata.api_version で設定）
3. 最新バージョン（現在: 2026-02-22）

レスポンスヘッダー

すべてのレスポンスには、実際に使用されたバージョンを示す BlueAI-Version ヘッダーが含まれます。

< HTTP/2 200
< BlueAI-Version: 2026-02-22
< Content-Type: application/json

現在のバージョン

現在の最新バージョンは 2026-02-22 です。

変更履歴エンドポイント

GET /api/v1/changelog でバージョン履歴と各バージョンの変更内容を取得できます。

curl https://api.blueai.jp/api/v1/changelog

{
  "object": "list",
  "data": [
    {
      "version": "2026-02-22",
      "date": "2026-02-22",
      "description": "Initial API version",
      "changes": [
        "Stable release of all v1 endpoints",
        "Stripe-style date-based versioning introduced",
        "BlueAI-Version header support",
        "Organization default API version via metadata"
      ]
    }
  ],
  "latest_version": "2026-02-22",
  "current_version": "2026-02-22",
  "all_versions": ["2026-02-22"]
}

後方互換性

同一バージョン内では後方互換性を維持します。以下の変更は互換性を損なわない変更として扱います：

• レスポンスへの新しいフィールドの追加
• 新しいエンドポイントの追加
• オプションのリクエストパラメータの追加
• 列挙型への新しい値の追加

破壊的変更

破壊的変更が必要な場合は、新しい日付バージョンを導入します。古いバージョンのリクエストは既存の動作を維持し、新しいバージョンを明示的に指定したリクエストのみ新しい動作になります。