バージョン管理の導入: Box API開発のマイルストーン
Boxでは、開発ワークフローを効率化し、開発者にさらなる安定性と柔軟性を促進するBox APIの重要な機能強化として、バージョン管理を発表します。
開発者を支援するための継続的な取り組みの一環として、一部のAPIエンドポイントにバージョン管理機能を導入し、シームレスな機能と、機能の更新と公式サポート終了のための信頼できる手段を確保します。
バージョン管理が重要な理由
バージョン管理は、互換性を維持するほか、開発者がAPIの動作の予期しない変更を心配することなく、安心してアプリケーションを開発および拡張できるようにするために極めて重要です。
バージョン管理により、開発者は、利用する機能をきめ細かく制御できるため、アプリケーションの進化に合わせて異なるAPIバージョン間をよりスムーズに移行できます。
Box APIのバージョン管理の仕組み
Box APIは、URLパスとヘッダーの両方でバージョン管理をサポートしています。開発者は、リクエスト内で必要なAPIバージョンを指定して、アプリケーションがAPIの対象バージョンを操作するようにできます。
デフォルトのバージョンはURLで指定されていますが、Box-Version
ヘッダーでは明示的なバージョンの宣言が可能であり、APIの操作に対する柔軟性と制御が実現します。
たとえば、https://upload.box.com/api/2.0/files/content
などのAPIエンドポイントに重大な変更があった場合は、https://upload.box.com/api/3.0/files/content
のように新しいエンドポイントが提供されます。アプリがURLに存在しないバージョンを呼び出すと、HTTP 404 — Not found
が返されます。
ただし、Box-Version
という新しいヘッダーを使用すると、デフォルトのエンドポイント内で異なるバージョンを使用することも可能です。次の例では、エンドポイントのバージョン2025.0
を使用して、すべての署名リクエストのリストを取得します。
curl --location 'https://api.box.com/2.0/sign_requests' \
--header 'Box-Version: 2025.0' \
--header 'Authorization: Bearer <>
Box-Version
ヘッダーで存在しないバージョンを指定すると、APIからHTTP 404 — Not found
エラーが返されます。
Box-Version
ヘッダーで非推奨のバージョンを指定すると、APIからDeprecation
ヘッダーが返されます。
Deprecation: date="Fri, 11 Nov 2023 23:59:59 GMT"
Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated
アプリケーションでは、これらのDeprecationヘッダーを監視し、更新を計画できるようにする必要があります。
リリーススケジュールと命名規則
Boxは計画されたリリーススケジュールに従うため、新しい重大な変更を特定のエンドポイントに導入できるのは、最大で1年に1回です。エンドポイントに新しいバージョンが追加されると、すべてのHTTPメソッド (GET/POST/PUT) が影響を受けます。
Boxの命名規則にはリリースの暦年が反映され、セキュリティまたはプライバシーの更新のためにインクリメンタルバージョン管理が使用されます。
たとえば、署名リクエストエンドポイントの新しいバージョンが2025年にリリースされた場合、その名前は2025.0
になります。リリース済みのバージョン2025.0
の署名リクエストでセキュリティの問題への対処が必要な場合、新しいバージョンには2025.1
というラベルが付けられます。
安定したそれぞれのバージョンは最低12か月間サポートされるため、開発者は、新しいバージョンに適応および移行するための十分な時間が得られます。新しいバージョンがリリースされると、以前のバージョンはすぐに非推奨になるため、新機能は追加されなくなります。
非推奨のバージョンは、Boxが廃止を決定するまで引き続き動作します。この公式サポート終了 (EOL) は、24か月前に発表されます。
重大な変更
Box APIの重大な変更は、通常はAPIの新しいメジャーバージョンに付随して、バージョン管理されているリリース内で発生します。既存の機能を損なわない微調整であれば、既存のAPIバージョンに組み込むことが可能です。
何が重大な変更と見なされるかについては、ガイドを参照してください。
SDKのバージョン管理
このバージョン管理戦略は、次世代SDKのみに適用されます。従来のSDKはメンテナンスの対象になりません。
APIの安定したバージョンも非推奨のバージョンも、次世代SDKでサポートされます。新しいバージョンが導入されると、そのバージョンがタグ付けされ、非推奨のすべてのバージョンとともに、対応するマネージャに含まれます。バージョンの公式サポートが終了すると、そのバージョンは対応するマネージャから削除されます。
たとえば、FileManager
のupdateFileByID
の初期状態は次のようになります。
class FilesManager {
async updateFileById(
fileId: string,
requestBody: UpdateFileByIdRequestBody,
queryParams: UpdateFileByIdQueryParams,
headers: UpdateFileByIdHeaders
): Promise < FileFull > {}
}
新しいバージョンが導入されると、元のバージョンは非推奨になります。
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> {}
}
元のバージョンの公式サポート終了が発表されると、次のようになります。
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の進化における重要なマイルストーンを示し、開発者の制御、安定性、柔軟性を強化します。Boxは、開発者エクスペリエンスの継続的な改善に取り組んでおり、バージョン管理はその目標に向けた重要なステップです。このバージョン管理の導入にあたり、引き続きご協力いただければ幸いです。
Box APIのバージョン管理に関する詳細なドキュメントについては、APIのバージョン戦略ガイドを参照してください。
フィードバックとコラボレーション
Box APIのバージョン管理をリリースするにあたり、皆さまからのフィードバックや見識に感謝しております。皆さまからのご意見は、バージョン管理戦略を策定し、Box Developer Communityのニーズを確実に満たすために役立ちます。Box APIのこの重要な側面を改善できるようにするためにも、バージョン管理に関するご意見やご提案、ご経験をお聞かせください。
forum.box.com (英語のみ) へのコメントをお待ちしています。