WorkivaにおけるAPIバージョニング
アプリケーション・プログラミング・インターフェース（API）のバージョニングは、変更を効果的に管理・伝達するために、APIの設計の異なるイテレータに一意の識別子を割り当てる重要な慣行です。そのプライマリな目的は後方互換性を維持することであり、新規APIバージョンがリリースされたときに、古いバージョンに依存しているスクリプトやアプリケーションが分割されないようにすることです。この安定性により、APIプロバイダーは既存ユーザーを混乱させることなくメジャーアップデート、バグ修正、新規機能を導入することができ、消費者は準備ができたときにシステムを移行するのに必要な時間とコントロールを付与することができます。最終的に、適切なAPIのバージョニングは、信頼性が高く、スケーラブルで、プロフェッショナルな開発エコシステムを上げます。
2026-01-01 APIバージョンリリース
2026年1月、Workivaは新規APIバージョン、2026-01-01 をリリースします。この新規バージョンは、一貫性の向上、新機能、旧機能の非推奨を含む、複数の領域にわたる大幅な改善を導入しています。2026-01-01 バージョンへのアップグレードの利点には、最新の Workiva Platform 機能との互換性の継続、セキュリティの強化、パフォーマンスの向上、新規機能の活用が含まれます。
新規 API バージョンの詳細については、Workiva API 2026-01-01 アップグレードガイド をご参照ください。
2022-01-01 API バージョンの非推奨
2026-01-01バージョンのリリースにより、古い2022-01-01バージョンは非推奨フェーズに入ります。この旧バージョンのサポートは2029年1月に終了するまで継続され、2022-01-01プロトタイプエンドポイントのサポートは2027年1月に終了します。
メモ: 2022-01-01 バージョンのほとんどの Prototype エンドポイントは、2026-01-01 バージョンの General Availability (GA) に昇格しました。
| バージョン | ステータス | エンドポイント・タイプ | 日没日 |
|---|---|---|---|
| 2026-01-01 | 一般提供 (GA) | すべて | 該当なし（現在） |
| 2022-01-01 | 非推奨 | プロトタイプ | 2027年1月 |
| 2022-01-01 | 非推奨 | GA | 2029年1月 |
API バージョンの比較
新規バージョンがリリースされると、Workiva Developers Hub のそのバージョンの API ドキュメントには、そのバージョンでの API の変更に関する詳細なドキュメントを含む Changelog セクションが含まれます。2026-01-01 バージョンには、2026-01-01 アップグレードガイド セクションがあり、そのバージョンの変更点の完全なウォークスルーがあります。
さらに、2つの異なるAPIバージョンで比較を実行するために利用可能な多くのオープンソースツールがあります。このタイプ別ツールにより、バージョン変更の迅速かつ詳細な比較が可能になります。オープンソースツールoasdiff にはウェブベースの Diff Calculator があり、2 つの API バージョン設定ファイル (oas.yaml) をアップロードし、変更点、変更履歴、または生の diff の比較を実行することができます。テキスト、yaml、json、html、マークダウンで結果を出力できます。
特定の API バージョンを参照
Workiva API はX-Version ヘッダーを利用して、使用する API バージョンを指定します。X-Versionヘッダーが渡されない場合、バージョンのデフォルトは非推奨の2022-01-01バージョンになります。
メモ: 2029年1月以降はX-Versionヘッダーが必須となり、これがないAPIコールはすべて失敗します。
Python経由のAPIリクエストでバージョンを指定するには、各APIリクエストのヘッダーにキーと値のペアを含めます。例:ヘッダー = {'X-Version': '2026-01-01'}.
現在指定できるのは、2026-01-01 または2022-01-01 のいずれかです。
2026-01-01バージョンには多くの分割変更があるため、X-Versionヘッダーが該当するバージョンに設定されていること、APIエンドポイントのURLパスとパラメータがそのバージョンの要求構造と一致していることを確認することが重要です。さらに、APIコールの応答書式設定と、バージョン間でその書式が異なる可能性を理解することも重要です。
例
GET リクエストの例
2026-01-01 バージョンと 2022-01-01 バージョンの両方について、Retrieve a List of Spreadsheets エンドポイントで GET リクエストを使用した例です (これらの例では、難読化のためにトークン変数としてベアラートークンを含んでいます)。
2026-01-01 バージョン
# 2026-01-01 バージョン # X-Versionヘッダーと依頼URLにメモ headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2026-01-01', } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', headers = headers, )2022-01-01バージョン
# 2022-01-01 バージョン # X-Versionヘッダーと依頼URLにメモ headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } resp = requests.get( 'https://api.app.wdesk.com/platform/v1/spreadsheets', headers = headers, )PATCH リクエストの例
以下は、2026-01-01 バージョンと 2022-01-01 バージョンの両方について、Partially Update a Single Section エンドポイントで PATCH リクエストを使用する例です (これらの例では、難読化の目的で、トークン変数としてベアラートークンを含んでいます)。
2026-01-01 バージョン
# 2026-01-01バージョン # X-VersionヘッダーとリクエストURLにメモ headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization':token, 'X-Version': '2026-01-01', } patch_op = [ { "op": "replace", "path": "/name", "value": "My New Section Name" } ] resp = requests.patch ( https://api.app.wdesk.com/documents/{documentId}/sections/{sectionId}', json = patch_op, ヘッダー = headers, )2022-01-01 バージョン
# 2022-01-01 バージョン # X-VersionヘッダーとリクエストURLにメモ headers = { 'Content-Type': 'application/json', 'Accept': 'application/json', 'Authorization': token, 'X-Version': '2022-01-01', } patch_op = [ { "op": "replace", "path": "/name", "value": "My New Section Name" } ] resp = requests.patch( f'https://api.app.wdesk.com/platform/v1/documents/{documentId}/sections/{sectionId}', json = patch_op, ヘッダー = headers, )ヒント: URLパスとパラメータの構造が該当するAPIバージョンと一致していることを確認することに加え、使用可能なパラメータオプションの詳細については、必ずドキュメントを確認してください。
例えば、上記の「単一のセクションを部分的に更新する」例では、2022-01-01 バージョンでは利用可能なパスオプションは 3 つ ( /名称 , /index , /parent ) ですが、2026-01-01 バージョンでは利用可能なパスオプションは 30 以上あります。
スクリプトと API のバージョン管理のベストプラクティス
必要なAPIバージョンは、アクティブなスクリプトやアプリケーションの状態、新規APIバージョンへのアップグレードのスケジュール、またはその他の要因によって異なりますが、以下にスクリプティングとAPIバージョニングに関するベストプラクティスをいくつか示します。
常にAPIバージョンを指定
APIプロバイダーのデフォルトバージョンに依存しないでください。すべてのAPIコールでバージョンを明示的に指定します。バージョンを明示的に指定することで、スクリプトやアプリケーションが実行するバージョンをコントロールできます。
バージョン定数の一元化
API バージ ョ ン を、 ス ク リ プ ト の先頭か、 あ る いは別の構成フ ァ イ ルで、 簡単に見つけ る こ と がで き る定数ま たは構成変数 と し て定義 し ます。これにより、トラブルシューティングが確実に効率化され、保守性が向上します。例：
# config.py またはメインスクリプトの先頭で API_VERSION = '2026-01-01' # リクエスト呼び出しで headers = { 'Accept': 'application/json', 'Authorization': token, 'X-Version'：API_VERSION, } resp = requests.get( 'https://api.app.wdesk.com/spreadsheets', ヘッダー = headers, )APIバージョンの混在を避ける
単一のスクリプトやアプリケーション内で API バージョンを混在させないでください。1つのスクリプトまたはアプリケーション内のすべてのAPIコールは、同じWorkiva APIバージョンを参照する必要があります（例えば、すべてのAPIコールは「2026-01-01」バージョンを使用する必要があります）。バージョンを混在させると、デバッグやリクエストスキーマ、レスポンス書式設定が複雑になり、スクリプトの挙動が予測できなくなったり、メンテナンスが複雑になったりします。
APIインタラクションロジックの分離
外部APIとのすべての通信を処理する専用のモジュールまたは関数設定（しばしば "ラッパー "または "クライアント "と呼ばれます）を作成します。このパターンでは、スクリプトの "ビジネスロジック "と "API通信ロジック "を分離します。APIが変更された場合（例えば、新規APIバージョンでエンドポイントURLやリクエスト／レスポンス構造が変更された場合）、 スクリプト全体ではなく、ラッパー関数だけを更新する必要があります。
非推奨のエンドポイントとパラメータを丁重に扱いましょう。
古いAPIバージョンから新規APIバージョンに移行する場合は、エンドポイントやパラメータの名前の変更や削除が行われる可能性があることを想定してください。スクリプトに堅牢なエラー処理と記録を含めるようにします。これは、スクリプト開発のベスト プラクティスをサポートし、バージョン関連のエラーを検出して記録する確率を高めるためです。
スクリプトのベストプラクティスについては、Workiva Scripting：開発のベストプラクティスの記事を参照してください。
非推奨の監視と計画
Workivaは、新規メジャーバージョンのリリースウィンドウを年に2回、春と秋に提供するように移行しています。リリース日が近づいても分割変更がなく、その期間のリリース候補が空であるイベントについては、Workivaはその時間にAPIの新規バージョンを更新しません。
Workiva API デベロッパーハブ ウェブサイトを積極的に追跡し、Workiva リリースノート を購読し、公開されたリリースと非推奨のスケジュール に従うことをお勧めします。非推奨 API バージョンを使用しているスクリプトは、いずれ分割されます。API バージョンのサンセット (使用終了) 日を知ることで、 の前に必要なアップグレード作業をスケジュールできます。
スクリプトの移行と検証
シームレスなAPIバージョン移行を確実にするには、並行テスト戦略を確立します。既存の本番用スクリプトをコピーし、そのコピーだけを新しいAPIバージョンをターゲットに修正（ヘッダー、URLパス、リクエスト/レスポンス構造の依頼者の変更を含む）してから、新旧両方のスクリプトをテストして、機能と出力を比較検証します。
コントロールされた環境で両者を並べて実行することで、新バージョンに完全に切り替えて旧バージョンを非推奨にする前に、安定した旧スクリプトを基準として、新スクリプトが生成する関数と結果が同一であることを監視して検証することができます。