2024年に、BoxではAPIの年ベースのバージョン管理を導入しました。2024年の年末に利用できたすべてのエンドポイントには、バージョン
2024.0が割り当てられました。APIユーザーが引き続きBox APIを使用するために必要な操作はありません。バージョンを指定してAPIコールを行うには、値2024.0を設定したbox-versionヘッダーをリクエストに含めてください。Box APIのバージョン管理の仕組み
Box APIは、
headerでのバージョン管理をサポートしています。どのバージョンを使用するかを決定するには、APIリファレンスとそこに記載されているサンプルリクエストを参照してください。headerにおけるバージョン管理
Box APIでは、有効なバージョン名を含むbox-versionヘッダーを処理します。たとえば、クライアントがバージョン2025.0を使用してすべての署名リクエストのリストを取得する場合、リクエストは次のようになります。
box-versionヘッダーが含まれ、リクエストの処理に使用されるバージョンを示します。2024年以降に導入されたエンドポイントは、バージョンが正しくない場合にエラーコード400を返すことがあります。バージョン管理のエラーの詳細については、を参照してください。
リクエストにバージョンが含まれていない場合、APIはデフォルトで、最初のBox APIバージョン2024.0 (年ベースのバージョン管理が導入される前のエンドポイントのバージョン) になります。ただし、非推奨の変更を適用する際にこの動作を利用することはお勧めしません。一貫性を確保するために、リクエストごとに必ずAPIバージョンを指定してください。アプリケーションにバージョンを認識させることで、アプリケーションを特定の機能セットに固定し、サポートされている期間中は一貫した動作が保証されます。
リリーススケジュールと命名規則
Boxでは、1年に1回、特定のエンドポイントに新しく重大な変更を行う場合があります。これにより、APIのバージョンが新しくなります。署名リクエストエンドポイントの新しいバージョンを導入すると、エンドポイントのすべてのパスとHTTPメソッドでそのバージョンがサポートされるようになります。 たとえば、署名リクエストのエンドポイントが新しいバージョンを受け取ると、そのバージョンは、次の表に示すすべてのエンドポイントに適用されます。命名規則
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のアクションを利用する際、ヘッダーに誤った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つのみ)。
-
エンドポイントの新しい
v2025_0バージョンが導入されます (以前のバージョンは非推奨になります)。 SDKでは、エンドポイントの新しいバージョンごとに新しいメソッドが導入されます。これらのメソッドは古いメソッドと同じマネージャに保存されますが、その名前と対応するクラスの末尾にはバージョン番号が追加されます。古いメソッドは非推奨となり、最小限のメンテナンスが行われる日付が通知されます。これは、エンドポイントの公式サポートが終了した状態と見なされる日付です。 -
APIエンドポイントが公式サポート終了 (EOL) としてマークされます。
SDKは、公式サポート終了 (EOL) のエンドポイントの削除を伴う重大な変更をリリースします。SDKの新しいメジャーバージョンを何度もリリースするのを避けるために、すべてのエンドポイントの公式サポート終了日を四半期ごとに特定の日にまとめるのが理想的です。
重大な変更と重大ではない変更
Box APIにおける重大な変更は、バージョン管理されたリリースの中で行われ、通常は新しいメジャーAPIバージョンを伴います。既存の機能を損なわない程度の微調整であれば、既存のAPIバージョンに統合できます。次の表では、重大な変更と重大ではない変更の例を示します。APIレスポンスの上位互換性
Boxは、バージョンの昇格なしに、いつでもAPIレスポンスに新規フィールド、省略可能なフィールド、または読み取り専用フィールドを追加することがあります。これらの変更は重大でないと見なされるため、事前の通知は不要です。 クライアントアプリケーションは、追加のJSONフィールドを許容し、認識していないフィールドを無視するよう実装する必要があります。不明なフィールドを拒否する厳格なレスポンススキーマ検証や逆シリアル化は推奨されません。これは、Boxが新しいフィールドを導入する際に、統合が機能しなくなる可能性があるためです。 長期的な安定性を確保するには:- アプリケーションが明示的に必要とする、ドキュメント化されたフィールドのみを統合する
- APIレスポンスと固定スキーマが厳密に一致することを想定しない
- マッピングされていないプロパティや予期しないプロパティを無視するようJSON解析ライブラリを構成する
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エンドポイントを呼び出すと、レスポンスには以下のようなヘッダーが含まれます。
バージョン管理に関する考慮事項
リクエストの作成時には、以下の点を考慮してください。- バージョン
2024.0のエンドポイントは、box-versionヘッダーでバージョンを指定しなくても呼び出し可能です。バージョンが指定されておらず、呼び出したエンドポイントの2024.0バージョンが存在しない場合、レスポンスではHTTPエラーコード400 - Bad Requestが返されます。 box-versionバージョンヘッダーが指定されていても、リクエストされたバージョンが存在しない場合、レスポンスではHTTPエラーコード400 - Bad Requestが返されます。
-
非推奨の動作を伴う呼び出しにより、レスポンスヘッダー
Box-API-Deprecated-Reasonと、詳細を確認するためのリンクが返されます。 - 非推奨に関するお知らせが開発者向け変更ログに掲載されます。
- 影響を受けるリソースと必要な対応を特定できるように、APIリファレンスが更新されます。影響を受けるエンドポイントには非推奨の長円形アイコンが表示されます。
- アプリに影響する後方互換性のない変更が差し迫っている場合は、その非推奨についてアプリの連絡先メールアドレスに問い合わせることがあります。