APIのバージョン戦略

Boxでは、特定のAPIエンドポイントに対してバージョン管理機能を提供しています。このバージョン管理システムにより、Boxがエンドポイントのバージョンを新しく導入した場合でも、既存のエンドポイントのバージョンに対してシームレスな機能が保証されます。 APIのバージョン管理により、Boxは、自社のプラットフォームを継続的に強化できると同時に、機能の更新や廃止のための信頼できる手段をサードパーティの開発者に提供することもできます。

今後予定されているAPIの変更について常に最新情報を把握できるように、変更ログを注視し、開発者コンソールの [アプリ情報] セクションで最新のメールアドレスを指定しておいてください。

2024年に、BoxではAPIの年ベースのバージョン管理を導入しました。2024年の年末に利用できたすべてのエンドポイントには、バージョン2024.0が割り当てられました。APIユーザーが引き続きBox APIを使用するために必要な操作はありません。バージョンを指定してAPIコールを行うには、値2024.0を設定したbox-versionヘッダーをリクエストに含めてください。

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

Box APIは、headerでのバージョン管理をサポートしています。どのバージョンを使用するかを決定するには、APIリファレンスとそこに記載されているサンプルリクエストを参照してください。

Box APIでは、有効なバージョン名を含むbox-versionヘッダーを処理します。たとえば、クライアントがバージョン2025.0を使用してすべての署名リクエストのリストを取得する場合、リクエストは次のようになります。

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

指定したバージョンが正しく、エンドポイントでサポートされている場合、レスポンスがクライアントに送信されます。エンドポイントが複数のバージョンで使用可能な場合、レスポンスにはbox-versionヘッダーが含まれ、リクエストの処理に使用されるバージョンを示します。2024年以降に導入されたエンドポイントは、バージョンが正しくない場合にエラーコード400を返すことがあります。バージョン管理のエラーの詳細については、こちらを参照してください。リクエストにバージョンが含まれていない場合、APIはデフォルトで、最初のBox APIバージョン2024.0 (年ベースのバージョン管理が導入される前のエンドポイントのバージョン) になります。ただし、非推奨の変更を適用する際にこの動作を利用することはお勧めしません。一貫性を確保するために、リクエストごとに必ずAPIバージョンを指定してください。アプリケーションにバージョンを認識させることで、アプリケーションを特定の機能セットに固定し、サポートされている期間中は一貫した動作が保証されます。

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

Boxでは、1年に1回、特定のエンドポイントに新しく重大な変更を行う場合があります。これにより、APIのバージョンが新しくなります。署名リクエストエンドポイントの新しいバージョンを導入すると、エンドポイントのすべてのパスとHTTPメソッドでそのバージョンがサポートされるようになります。たとえば、署名リクエストのエンドポイントが新しいバージョンを受け取ると、そのバージョンは、次の表に示すすべてのエンドポイントに適用されます。

メソッド	リクエストURL	説明
GET	`https://api.box.com/2.0/sign_requests/:id`	特定の署名リクエストの詳細を取得します。
GET	`https://api.box.com/2.0/sign_requests/`	すべての署名リクエストを取得します。
POST	`https://api.box.com/2.0/sign_requests/`	新しい署名リクエストを作成します。
POST	`https://api.box.com/2.0/sign_requests/:id/resend`	特定の署名リクエストを再度送信します。
POST	`https://api.box.com/2.0/sign_requests/:id/cancel`	特定の署名リクエストをキャンセルします。

命名規則

APIの新しいバージョンは、リリースされた暦年に従ってラベルが付けられます。例: 署名リクエストのエンドポイントの新しいバージョンが2025年にリリースされた場合、その名前は2025.0となります。 Boxは、1年に1回、APIエンドポイントに新しく重大な変更を行う場合がありますが、セキュリティやプライバシーに関する懸念に対処するためにさらに重大な変更をリリースする権利を留保します。このような場合、新しいバージョンではサフィックスが1ずつ増加します。例: 以前にリリースされた署名リクエストのバージョン2025.0でセキュリティの問題に対処する必要がある場合、新しいバージョンには2025.1というラベルが付きます。安定した各バージョンは最低12か月間サポートされます。つまり、新しいバージョンがリリースされると、以前のバージョンは非推奨となり、使用することはできますが、新機能が追加されなくなります。また、12か月経たずに新しいバージョンがリリースされることはありません。アプリを更新して最新の安定したAPIバージョンにリクエストを実行することを強くお勧めします。ただし、アプリで使用している安定したバージョンがサポートされなくなると、HTTPエラーコード400 - Bad Requestを含むレスポンスが返されます。詳細については、バージョン管理のエラーを参照してください。

エンドポイントのバージョン管理に関する表示

APIの現在の状態が常にわかるようにし、バージョン管理されているAPIリファレンスが読みやすくなるよう、影響を受けるエンドポイントにはx-stability-levelタグまたはdeprecated属性に基づいた長円形アイコンが表示されます。

APIリファレンスのエンドポイントで使用されている、ベータを示す長円形アイコンの例

スキーマ要素	長円形アイコンの名前	説明
`x-stability-level: beta`	ベータ	ベータと表示されているエンドポイントは、BoxのMain Beta Agreementに従い提供されているため、利用可能な機能が変更される可能性があります。ベータ版のエンドポイントが安定すると、ベータという表示が削除されます。
`x-stability-level: stable`、または`x-stability-level`タグなし	最新バージョン	最新バージョンとは、エンドポイントの最新の安定したバージョンを示します。
`deprecated: true`	非推奨	エンドポイントは非推奨です。つまり、このエンドポイントは引き続き使用できますが、新機能が追加されなくなります。このようなエンドポイントには、`deprecated`属性を`true`に設定した状態で注釈が付けられています。

バージョン管理のエラー

呼び出しなど、バージョン管理されている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つのみ)。

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

エンドポイントの新しい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> {}
}
```
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バージョンに統合できます。次の表では、重大な変更と重大ではない変更の例を示します。

APIの変更	重大な変更
新しいエンドポイント	いいえ
リクエストの新しい読み取り専用フィールドまたは省略可能なフィールド	いいえ
リクエストの新しい必須フィールド	はい
リクエストの新しい文字列定数	はい
非推奨	いいえ
廃止/公式サポート終了となったエンドポイント	はい
フィールド、データ型、文字列定数の名前変更/再構築	はい
フィールド検証の制限を強化する変更	はい
フィールド検証の制限を緩和する変更	いいえ
操作によって返されるHTTPステータスコードの変更	はい
宣言済みプロパティの削除	はい
APIまたはAPIパラメータの削除または名前変更	はい
必須のリクエストヘッダーの追加	はい
エラーコードの追加	いいえ
エラーコードの削除または変更	はい
列挙へのメンバーの追加	はい

oasdiffツールを使用すると、重大と思われる変更の大半を検出できます。

Forward compatibility of API responses

Box may add new, optional, or read-only fields to API responses at any time without a version bump. These changes are considered non-breaking and require no advance notification. Client applications must be implemented to tolerate additional JSON fields and ignore fields they do not recognize. Strict response schema validation or deserialization that rejects unknown fields is discouraged, as it may cause integrations to break when Box introduces new fields. To ensure long-term stability:

Integrate only the documented fields your application explicitly requires
Do not assume API responses will exactly match a fixed schema
Configure JSON parsing libraries to ignore unmapped or unexpected properties

AIエージェントの構成のバージョン管理

AIエージェントのバージョン管理により、開発者はモデルのバージョン管理をより詳細に制御できるようになり、レスポンスの一貫性が確保されます。詳細については、AIエージェントの構成のバージョン管理ガイドを参照してください。

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

Box APIとBox SDKの新しいバージョンがリリースされると、それより前のバージョンは廃止されます。Boxでは、バージョンを廃止する少なくとも24か月前に、そのバージョンをdeprecatedとマークします。つまり、非推奨バージョンの公式サポートが24か月経たずに終了することはありません。同様に、正式リリース (GA) されている個々のAPIについても、GAバージョンから削除する少なくとも24か月前にそのAPIをdeprecatedとして宣言します。 Boxは、APIのメジャーバージョンを上げる際 (2025.0から2026.0など)、現在のバージョン (この例では2025.0) が即座に非推奨となることを発表し、その発表から24か月後にサポートを終了します。サービスのセキュリティや状態の信頼性に問題がある場合は、このポリシーに例外を認めることがあります。 APIが非推奨としてマークされている場合は、できるだけ早く最新バージョンに移行することを強くお勧めします。場合によっては、元のAPIが非推奨になってしばらくしてから、新しいアプリケーションで新しいAPIの使用を開始する必要があることを案内することもあります。お客様が非推奨のAPIエンドポイントを呼び出すと、レスポンスには以下のようなヘッダーが含まれます。

Deprecation: date="Fri, 11 Nov 2026 23:59:59 GMT"
Box-API-Deprecated-Reason: /reference/deprecated

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

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

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

バージョン2024.0のエンドポイントは、box-versionヘッダーでバージョンを指定しなくても呼び出し可能です。バージョンが指定されておらず、呼び出したエンドポイントの2024.0バージョンが存在しない場合、レスポンスではHTTPエラーコード400 - Bad Requestが返されます。
box-versionバージョンヘッダーが指定されていても、リクエストされたバージョンが存在しない場合、レスポンスではHTTPエラーコード400 - Bad Requestが返されます。

詳細については、バージョン管理のエラーを参照してください。 APIに含まれるリソースまたはリソースのプロパティが非推奨になると、その変更は以下の1つ以上の方法で伝えられます。

非推奨の動作を伴う呼び出しにより、レスポンスヘッダーBox-API-Deprecated-Reasonと、詳細を確認するためのリンクが返されます。
```
box-version: 2025.0
Deprecation: version="version", date="date"
Box-API-Deprecated-Reason: /reference/deprecated
```
非推奨に関するお知らせが開発者向け変更ログに掲載されます。
影響を受けるリソースと必要な対応を特定できるように、APIリファレンスが更新されます。影響を受けるエンドポイントには非推奨の長円形アイコンが表示されます。
アプリに影響する後方互換性のない変更が差し迫っている場合は、その非推奨についてアプリの連絡先メールアドレスに問い合わせることがあります。

その他のリソース

APIリファレンス

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

​headerにおけるバージョン管理

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

​命名規則

​エンドポイントのバージョン管理に関する表示

​バージョン管理のエラー

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

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

​Forward compatibility of API responses

​AIエージェントの構成のバージョン管理

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

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

​その他のリソース

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

`header`におけるバージョン管理

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

命名規則

エンドポイントのバージョン管理に関する表示

バージョン管理のエラー

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

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

Forward compatibility of API responses

AIエージェントの構成のバージョン管理

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

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

その他のリソース