APIのバージョン戦略
APIのバージョン戦略
Boxでは、特定のAPIエンドポイントに対してバージョン管理機能を提供しています。このバージョン管理システムにより、Boxがエンドポイントのバージョンを新しく導入した場合でも、既存のエンドポイントのバージョンに対してシームレスな機能が保証されます。
APIのバージョン管理により、Boxは、自社のプラットフォームを継続的に強化できると同時に、機能の更新や廃止のための信頼できる手段をサードパーティの開発者に提供することもできます。
Box APIのバージョン管理の仕組み
リクエストで使用されるAPIのデフォルトのバージョンは、呼び出すエンドポイントのURLで指定します。フローの例を以下に示します。
-
バージョンヘッダーを指定せずにアップロードエンドポイントを呼び出すと、URLで定義されている
2.0
バージョンが使用されます。 -
Box APIでは、以下に該当する
Box-Version
ヘッダーを処理します。Box-Version: 2025.0
のような有効なバージョン名を含むhttps://api.box.com/2.0/files/:file_id/metadata
に送信される
-
指定したバージョンが正しい場合は、クライアントにレスポンスが返されます。リクエストで
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メソッドに対応しています。たとえば、署名リクエストのエンドポイントには以下のメソッドが含まれます。
メソッド | リクエスト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 | 特定の署名リクエストをキャンセルします。 |
署名リクエストエン ドポイントの新しいバージョンを導入すると、上記のすべてのパスとHTTPメソッドでそのバージョンがサポートされるようになります。エンドポイントのバージョンに関する包括的な情報については、Box APIリファレンスを参照してください。
命名規則
APIの新しいバージョンは、リリースされた暦年に従ってラベルが付けられます。たとえば、署名リクエストのエンドポイントの新しいバージョンが2025年にリリースされた場合、その名前は2025.0
となります。
Boxは、1年に1回、APIエンドポイントに新しく重大な変更を行う場合がありますが、セキュリティやプライバシーに関する懸念に対処するためにさらに重大な変更をリリースする権利を留保します。このような場合、新しいバージョンではサフィックスが1ずつ増加します。たとえば、以前にリリースされた署名リクエストのバージョン2025.0
でセキュリティの問題に対処する必要がある場合、新しいバージョンには2025.1
というラベルが付きます。
安定した各バージョンは最低12か月間サポートされます。つまり、新しいバージョンがリリースされると、以前のバージョンは非推奨となり、使用することはできますが、新機能が追加されなくなります。また、12か月経たずに新しいバージョンがリリースされることはありません。
アプリを更新して最新の安定したAPIバージョンにリクエストを実行することを強くお勧めします。ただし、アプリで使 用している安定したバージョンがサポートされなくなると、HTTPエラーコード404 - Not Found
を含むレスポンスが返されます。詳細については、バージョン管理のエラーを参照してください。
リクエストにバージョンが含まれていない場合、APIはデフォルトのBox APIバージョンV2
になります。ただし、非推奨の変更を適用するためにこの動作を利用することはお勧めしません。アプリを更新する際は、リクエストごとに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種類があります。