APIのバージョン戦略

Boxでは、特定のAPIエンドポイントに対してバージョン管理機能を提供しています。このバージョン管理システムにより、Boxがエンドポイントのバージョンを新しく導入した場合でも、既存のエンドポイントのバージョンに対してシームレスな機能が保証されます。

APIのバージョン管理により、Boxは、自社のプラットフォームを継続的に強化できると同時に、機能の更新や廃止のための信頼できる手段をサードパーティの開発者に提供することもできます。

Box APIのバージョン管理の仕組み

リクエストで使用されるAPIのデフォルトのバージョンは、呼び出すエンドポイントのURLで指定します。フローの例を以下に示します。

1. バージョンヘッダーを指定せずにアップロードエンドポイントを呼び出すと、URLで定義されている2.0バージョンが使用されます。

2. Box APIでは、以下に該当するbox-versionヘッダーを処理します。

   • box-version: 2025.0のような有効なバージョン名を含む
   • https://api.box.com/2.0/files/:file_id/metadataに送信される

3. 指定したバージョンが正しい場合は、クライアントにレスポンスが返されます。リクエストでbox-versionヘッダーを指定した場合、レスポンスにはこのヘッダーも含まれます。デフォルトでは、このヘッダーはレスポンスに存在しません。バージョンが正しくない場合は、HTTPコード400のエラーがクライアントに返されます。

APIの動作に大きな変更があると、新しいエンドポイントは新しいURLで公開されます。たとえば、https://upload.box.com/api/2.0/files/contentでは、Boxにファイルをアップロードする際にマルチパートのコンテンツタイプをサポートしています。このAPIの新しいバージョンでこのコンテンツタイプがサポートされなくなると、新しいバージョンは新しいURLhttps://upload.box.com/api/3.0/files/contentでリリースされます。

リリーススケジュールと命名規則

Boxでは、1年に1回、特定のエンドポイントに新しく重大な変更を行う場合があります。エンドポイントは、特定のAPIルート内でサポートされているすべてのHTTPメソッドに対応しています。たとえば、署名リクエストのエンドポイントには以下のメソッドが含まれます。

署名リクエストエンドポイントの新しいバージョンを導入すると、上記のすべてのパスとHTTPメソッドでそのバージョンがサポートされるようになります。エンドポイントのバージョンに関する包括的な情報については、Box APIリファレンスを参照してください。

命名規則

APIの新しいバージョンは、リリースされた暦年に従ってラベルが付けられます。たとえば、署名リクエストのエンドポイントの新しいバージョンが2025年にリリースされた場合、その名前は2025.0となります。

Boxは、1年に1回、APIエンドポイントに新しく重大な変更を行う場合がありますが、セキュリティやプライバシーに関する懸念に対処するためにさらに重大な変更をリリースする権利を留保します。このような場合、新しいバージョンではサフィックスが1ずつ増加します。たとえば、以前にリリースされた署名リクエストのバージョン2025.0でセキュリティの問題に対処する必要がある場合、新しいバージョンには2025.1というラベルが付きます。

安定した各バージョンは最低12か月間サポートされます。つまり、新しいバージョンがリリースされると、以前のバージョンは非推奨となり、使用することはできますが、新機能が追加されなくなります。また、12か月経たずに新しいバージョンがリリースされることはありません。

アプリを更新して最新の安定したAPIバージョンにリクエストを実行することを強くお勧めします。ただし、アプリで使用している安定したバージョンがサポートされなくなると、HTTPエラーコード400 - Bad Requestを含むレスポンスが返されます。詳細については、バージョン管理のエラーを参照してください。

リクエストにバージョンが含まれていない場合、APIはデフォルトで、最初のBox APIバージョン (年ベースのバージョン管理が導入される前のバージョン) になります。ただし、非推奨の変更を適用する際にこの動作を利用することはお勧めしません。一貫性を確保するために、リクエストごとに必ずAPIバージョンを指定してください。アプリケーションにバージョンを認識させることで、アプリケーションを特定の機能セットに固定し、サポートされている期間中は一貫した動作が保証されます。

APIバージョンの呼び出し

Box APIのバージョンは、アプリでリクエストするbox-versionヘッダーで明示的に宣言します。次に例を示します。

curl --location 'https://api.box.com/2.0/sign_requests' \
    --header 'box-version: 2025.0' \
    --header 'Authorization: Bearer …

クライアントは、作成されたすべての署名リクエストのリストを取得し、バージョン2025.0を要求します。使用可能なAPIにはサポートされているバージョンがいくつかあるため、使用するバージョンをbox-versionヘッダーで指定します。APIのバージョンには、安定、非推奨、不安定の3種類があります。

バージョン管理のエラー

ヘッダーでの正しくないAPIバージョンの呼び出し

box-versionヘッダーで指定されたAPIバージョンが正しくない場合、レスポンスではHTTP 400 - Bad Request errorが返されます。このエラーレスポンスの構造は次のようになります。

{
  "type": "error",
  "status": 400,
  "code": "invalid_api_version",
  "message":  "Some error message",
  "context_info": {
    "conflicts": [
      "box_version value must be in the format of YYYY.MM"
    ]
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/versioning-errors/"
}

エラーメッセージには、エラーに関する情報のほか、box-versionヘッダーに適切と思われる値が含まれます。以下に例を示します。

• The 'box-version' header supports only one header value per request, do not use comas. - ヘッダーに複数の値がコンマで区切って含まれている場合。
• Missing required box-version header. - ヘッダーが存在しないものの、必要な場合。
• Unsupported API version specified in 'box-version' header. Supported API versions: [LIST_OF_SUPPORTED_VERSIONS_COMA_SEPARATED] - 指定されたバージョンがAPIでサポートされていない場合。

非推奨のAPIの呼び出し

Boxで非推奨としてマークされたAPIバージョンをお客様が使用した場合も、APIは通常どおり応答します。ただし、非推奨になった日付を示すDeprecationヘッダーが追加されます。次に例を示します。

Deprecation: date="Fri, 11 Nov 2023 23:59:59 GMT"
Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated

お客様はAPIレスポンスを監視し、このヘッダーが表示されたら新しいAPIバージョンへの移行を計画する必要があることに留意する必要があります。

Box SDKのバージョン管理の仕組み

このバージョン戦略は、次世代のSDKにのみ適用されます。Box SDKはすべてのバージョンに対応というSDKのアプローチをサポートしています。つまり、SDKの各リリースでは、現在サポートされている任意のバージョンのすべてのエンドポイントにアクセスできます。生成されたすべてのSDKはマネージャのアプローチを使用します。このアプローチでは、同じドメインを使用するすべてのエンドポイントを1つのマネージャにグループ化します。たとえば、FolderManagerには、create_folder、get_folder_by_id、update_folder_by_id、delete_folder_by_id、get_folder_items、copy_folderのメソッドが含まれます。この分割はx-box-tagフィールドの値に基づいて行われます (このフィールドは公開APIサービスの仕様で各メソッドに割り当てられています)。ほとんどの場合、これはエンドポイントURLのルートに対応していますが、必ずしもそうとは限りません。たとえば、FolderManagerにはhttps://api.box.com/2.0/foldersというルートURLを使用するメソッドが含まれますが、同じベースURLはSharedLinkFoldersManagerのいくつかのメソッドでも使用されています。すべてのマネージャへの参照は、1つのBoxクライアントオブジェクトの下に保存されます。

エンドポイントのライフサイクルの例を見てみましょう。

1. 初期状態 (使用できるバージョンは1つのみ)。

    class FilesManager {
        async updateFileById(
            fileId: string,
            requestBody: UpdateFileByIdRequestBody,
            queryParams: UpdateFileByIdQueryParams,
            headers: UpdateFileByIdHeaders
        ): Promise < FileFull > {}
    }

2. エンドポイントの新しいv2025_0バージョンが導入されます (以前のバージョンは非推奨になります)。

   SDKでは、エンドポイントの新しいバージョンごとに新しいメソッドが導入されます。これらのメソッドは古いメソッドと同じマネージャに保存されますが、その名前と対応するクラスの末尾にはバージョン番号が追加されます。古いメソッドは非推奨となり、最小限のメンテナンスが行われる日付が通知されます。これは、エンドポイントの公式サポートが終了した状態と見なされる日付です。

    class FilesManager {
        /**
         * @deprecated This endpoint will be EOL'ed after 05-2026.
            */
        async updateFileById(
            fileId: string,
            requestBody: UpdateFileByIdRequestBody,
            queryParams: UpdateFileByIdQueryParams,
            headers: UpdateFileByIdHeaders
        ): Promise<FileFull> {}

        async updateFileById_2025_0(
            fileId: string,
            requestBody: UpdateFileByIdRequestBody_2025_0,
            queryParams: UpdateFileByIdQueryParams_2025_0,
            headers: UpdateFileByIdHeaders_2025_0
        ): Promise<FileFull_2025_0> {}
    }

3. APIエンドポイントが公式サポート終了 (EOL) としてマークされます。

   SDKは、公式サポート終了 (EOL) のエンドポイントの削除を伴う重大な変更をリリースします。SDKの新しいメジャーバージョンを何度もリリースするのを避けるために、すべてのエンドポイントの公式サポート終了日を四半期ごとに特定の日にまとめるのが理想的です。

    class FilesManager {
        async updateFileById_2025_0(
            fileId: string,
            requestBody: UpdateFileByIdRequestBody_2025_0,
            queryParams: UpdateFileByIdQueryParams_2025_0,
            headers: UpdateFileByIdHeaders_2025_0
        ): Promise < FileFull_2025_0 > {}
    }

重大な変更と重大ではない変更

Box APIにおける重大な変更は、バージョン管理されたリリースの中で行われ、通常は新しいメジャーAPIバージョンを伴います。既存の機能を損なわない程度の微調整であれば、既存のAPIバージョンに統合できます。次の表では、重大な変更と重大ではない変更の例を示します。

AI agent configuration versioning

AI agent versioning gives the developers more control over model version management and ensures consistent responses. For details, see AI agent configuration versioning guide.

サポートポリシーと非推奨情報

Box APIとBox SDKの新しいバージョンがリリースされると、それより前のバージョンは廃止されます。Boxでは、バージョンを廃止する少なくとも24か月前に、そのバージョンをdeprecatedとマークします。つまり、非推奨バージョンの公式サポートが24か月経たずに終了することはありません。同様に、正式リリース (GA) されている個々のAPIについても、GAバージョンから削除する少なくとも24か月前にそのAPIをdeprecatedとして宣言します。

Boxは、APIのメジャーバージョンを上げる際 (2024.0から2025.0など)、現在のバージョン (この例では2024.0) が即座に非推奨となることを発表し、その発表から24か月後にサポートを終了します。サービスのセキュリティや状態の信頼性に問題がある場合は、このポリシーに例外を認めることがあります。

APIが非推奨としてマークされている場合は、できるだけ早く最新バージョンに移行することを強くお勧めします。場合によっては、元のAPIが非推奨になってしばらくしてから、新しいアプリケーションで新しいAPIの使用を開始する必要があることを案内することもあります。

お客様が非推奨のAPIエンドポイントを呼び出すと、レスポンスには以下のようなヘッダーが含まれます。

Deprecation: date="Fri, 11 Nov 2023 23:59:59 GMT"
Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated

この日付は、いつこのバージョンが非推奨としてマークされたかをクライアントに示しています。

バージョン管理に関する考慮事項

リクエストの作成時には、以下の点を考慮してください。

• バージョンを指定しないと、サービスによって最初のバージョン (年ベースのバージョン管理が導入される前に存在していたバージョン) が返されます。最初のバージョンが存在しない場合、レスポンスでは、HTTPエラーコード400 - Bad Requestが返されます。
• バージョンヘッダーが指定されていても、リクエストされたバージョンを利用できない場合、レスポンスではHTTPエラーコード400 - Bad Requestが返されます。

詳細については、バージョン管理のエラーを参照してください。

APIに含まれるリソースまたはリソースのプロパティが非推奨になると、その変更は以下の1つ以上の方法で伝えられます。

• 非推奨の動作を伴う呼び出しにより、レスポンスヘッダーBox-API-Deprecated-Reasonと、詳細を確認するためのリンクが返されます。

    box-version: 2023.0
    Deprecation: version="version", date="date"
    Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated

• 非推奨に関するお知らせが開発者向け変更ログに掲載されます。
• 影響を受けるリソースと必要な対応を特定できるように、APIリファレンスが更新されます。
• アプリに影響する後方互換性のない変更が差し迫っている場合は、その非推奨についてアプリの連絡先メールアドレスに問い合わせることがあります。

その他のリソース

• APIリファレンス