APIのバージョン戦略

Box provides versioning capabilities for selected API endpoints. The version control system guarantees seamless functioning of existing endpoint versions, even if Box introduces new ones.

API versioning empowers Box to continually enhance its platform, while also offering third-party developers a reliable avenue for feature updates and deprecations.

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

The default version of the API used in any requests is specified in the URL of the endpoint you call. An example flow looks like this:

1. When calling the upload endpoint without any version header specified, you hit the 2.0 version defined in the URL.

2. Box API processes the Box-Version header which should:

   • Box-Version: 2025.0のような有効なバージョン名を含む
   • https://api.box.com/2.0/files/:file_id/metadataに送信される
3. 指定したバージョンが正しい場合は、クライアントにレスポンスが返されます。リクエストで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メソッドに対応しています。たとえば、署名リクエストのエンドポイントには以下のメソッドが含まれます。

署名リクエストエンドポイントの新しいバージョンを導入すると、上記のすべてのパスとHTTPメソッドでそのバージョンがサポートされるようになります。エンドポイントのバージョンに関する包括的な情報については、Box APIリファレンスを参照してください。

命名規則

APIの新しいバージョンは、リリースされた暦年に従ってラベルが付けられます。たとえば、署名リクエストのエンドポイントの新しいバージョンが2025年にリリースされた場合、その名前は2025.0となります。

Boxは、1年に1回、APIエンドポイントに新しく重大な変更を行う場合がありますが、セキュリティやプライバシーに関する懸念に対処するためにさらに重大な変更をリリースする権利を留保します。このような場合、新しいバージョンではサフィックスが1ずつ増加します。たとえば、以前にリリースされた署名リクエストのバージョン2025.0でセキュリティの問題に対処する必要がある場合、新しいバージョンには2025.1というラベルが付きます。

Each stable version is supported for a minimum of 12 months. This means that when a new version is released, the previous version becomes deprecated and will be available for use, but no new features will be added. It also means, that a new version cannot be released sooner than every 12 months.

アプリを更新して最新の安定した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種類があります。

Versioning errors

URLでの正しくないAPIバージョンの呼び出し

Boxのドキュメントでは、APIのURLが示されています。たとえば、署名リクエストのエンドポイントへのアクセスにはhttps://api.box.com/2.0/sign_requests/を使用します。お客様が誤ってhttps://api.box.com/3.0/sign_requests/のような正しくないバージョンを呼び出すと、レスポンスではHTTP error code 404 - Not Foundエラーが返されます。

非推奨のAPIの呼び出し

Boxで非推奨としてマークされたAPIバージョンをお客様が使用した場合も、APIは通常どおり応答します。ただし、非推奨になった日付を示すDeprecationヘッダーが追加されます。次に例を示します。

Deprecation: date="Fri, 11 Nov 2023 23:59:59 GMT"
Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated

お客様はAPIレスポンスを監視し、このヘッダーが表示されたら新しいAPIバージョンへの移行を計画する必要があることに留意する必要があります。

存在しないバージョンの呼び出し

公式サポートが終了した古いAPIバージョン (2023.0など) をお客様が使用しようとすると、レスポンスではHTTP error code 404 - Not Foundが返されます。詳細については、URLでの正しくない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. 初期状態 (使用できるバージョンは1つのみ)。

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

2. エンドポイントの新しい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> {}
}

3. 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バージョンに統合できます。次の表では、重大な変更と重大ではない変更の例を示します。

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

When new versions of the Box APIs and Box SDKs are released, earlier versions will be retired. Box marks a version as deprecated at least 24 months before retiring it. In other words, a deprecated version cannot become end-of-life sooner than after 24 months. Similarly, for individual APIs that are generally available (GA), Box declares an API as deprecated at least 24 months in advance of removing it from the GA version.

Boxは、APIのメジャーバージョンを上げる際 (2024.0から2025.0など)、現在のバージョン (この例では2024.0) が即座に非推奨となることを発表し、その発表から24か月後にサポートを終了します。サービスのセキュリティや状態の信頼性に問題がある場合は、このポリシーに例外を認めることがあります。

APIが非推奨としてマークされている場合は、できるだけ早く最新バージョンに移行することを強くお勧めします。場合によっては、元のAPIが非推奨になってしばらくしてから、新しいアプリケーションで新しいAPIの使用を開始する必要があることを案内することもあります。

お客様が非推奨のAPIエンドポイントを呼び出すと、レスポンスには以下のようなヘッダーが含まれます。

Deprecation: date="Fri, 11 Nov 2023 23:59:59 GMT"
Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated

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

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

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

• バージョンを指定しないと、サービスによってデフォルトのバージョンが返されますが、これは最新バージョンではない場合があります。
• バージョンヘッダーがない場合、デフォルトのリソースバージョンは、URLに含まれるバージョンによって決まります。
• バージョンヘッダーが指定されていても、リクエストされたバージョンを利用できない場合、レスポンスではHTTPエラーコード404 - Not Foundが返されます。

APIに含まれるリソースまたはリソースのプロパティが非推奨になると、その変更は以下の1つ以上の方法で伝えられます。

• 非推奨の動作を伴う呼び出しにより、レスポンスヘッダーBox-API-Deprecated-Reasonと、詳細を確認するためのリンクが返されます。

Box-Version: 2023.0
Deprecation: version="version", date="date"
Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated

• 非推奨に関するお知らせが開発者向け変更ログに掲載されます。
• 影響を受けるリソースと必要な対応を特定できるように、APIリファレンスが更新されます。
• アプリに影響する後方互換性のない変更が差し迫っている場合は、その非推奨についてアプリの連絡先メールアドレスに問い合わせることがあります。

その他のリソース

• APIリファレンス