バージョン管理の導入: Box API開発のマイルストーン

Image by freepik

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 (英語のみ) へのコメントをお待ちしています。