APIバージョニングとは？外部連携の互換性を守る設計と発注時の確認点

連携先の SaaS から「旧バージョンの API は 2027 年◯月で提供を終了します」という通知メールが届いたとき、あなたは社内の問い合わせに即答できるでしょうか。「うちのシステムは止まるのか」「対応にいくらかかるのか」「いつまでに動けばいいのか」という三つの問いは、情報システム部門に真っ先に飛んできます。あるいは、開発会社から届いた見積書に「APIバージョニング対応」という行があり、その金額が妥当なのか、そもそも今必要なのかを判断できずに保留にしている、という状況かもしれません。

この判断が難しいのには理由があります。APIバージョニングを解説した記事の多くは、API を「提供する側」のエンジニアに向けて書かれているからです。エンドポイントの設計方法やヘッダーの実装例は詳しく載っていても、「発注側は何を決めればよいのか」「見積のどこを見ればよいのか」には答えていません。用語を調べても、自社の意思決定には直結しないまま終わってしまいます。

しかし、発注側が押さえるべき論点はそれほど多くありません。「その変更は自社の改修が必要な種類のものか（破壊的変更かどうか）」「バージョンの指定方式は何を選び、なぜそうしたのか」「廃止までにどれくらいの猶予があるのが一般的か」「要件定義・見積・保守契約のどこに何を書き込むか」の四点を押さえれば、技術的な実装を理解していなくても、開発会社と対等に会話し、予算と契約に落とし込むことができます。

本記事では、APIバージョニングの基本的な仕組みから、後方互換性と破壊的変更の見分け方、URL・ヘッダー・クエリパラメータという 3 方式の違い、非推奨から廃止までのライフサイクルの実例、そして発注時に確認すべき 7 つの項目までを、発注する立場から解説します。

—Free Download / 資料ダウンロード

システム開発 完全チェックリスト――発注前・発注中・完了後の3フェーズで使えるチェック集

この資料でわかること

システム開発の外注・発注を初めて経験する担当者や、過去に失敗を経験した担当者が、発注プロセスの各フェーズで「何をチェックすべきか」を明確に把握できるようにする。

こんな方におすすめです

• 初めてシステム開発を外注する担当者
• 過去の発注で失敗を経験した方
• ベンダー選定の基準が分からない方

詳しく見る

フォームから無料ダウンロード

お名前必須

会社名必須

メールアドレス必須

電話番号任意

ご質問・ご要望任意

プライバシーポリシーに同意の上、送信します。

ダウンロードする

入力いただいたメールアドレスにPDFをお送りします。

APIバージョニングとは｜APIバージョン管理で互換性を保つ仕組み

APIバージョニングの定義と「複数バージョンの並行提供」という考え方

APIバージョニング（API バージョン管理）とは、同じ API に複数のバージョンを設けて並行して提供し、API を利用する側が自分たちのタイミングで新しいバージョンへ移行できるようにする仕組みです。

具体的なイメージで説明します。ある SaaS が受注データを取得する API を公開しているとします。この API に仕様変更が入るとき、バージョニングが設計されていれば、次のような状態になります。

• https://api.example.com/v1/orders — 従来の仕様のまま動き続ける
• https://api.example.com/v2/orders — 新しい仕様で追加された窓口

重要なのは、v1 と v2 が同時に生きているという点です。API を提供する側は新しい機能を v2 で公開し、利用する側は既存の連携を v1 のまま動かし続けながら、都合のよい時期に v2 への切り替え作業を計画できます。もしバージョンという概念がなく、窓口が一つしかなければ、提供側が仕様を変えた瞬間に全利用者のシステムが影響を受けます。

ここで発注側が最初に抱きやすい誤解が「バージョンを分ける＝同じものを二重に作るので、開発費が倍になるのではないか」というものです。実際には、v1 と v2 で処理の大部分は共通化され、差分となる部分だけが分岐します。バージョニングのコストの中心は、二重開発ではなく「どのバージョンをいつまで維持するかを決め、それを守り続ける運用」の側にあります。この点を押さえておくと、後半で扱う見積・保守契約の判断がしやすくなります。

なお、API そのものの役割や、システム連携でどう使われるのかを先に整理したい場合は、APIの基礎と活用イメージを先にご覧いただくと、本記事の内容が理解しやすくなります。

APIバージョン管理・ソフトウェアのバージョン管理・Gitのバージョン管理の違い

「バージョン管理」という言葉は複数の文脈で使われるため、社内の会話で話がかみ合わなくなることがあります。発注側として区別しておきたいのは次の三つです。

このうち、発注側の予算と契約に直結するのは一番上の APIバージョン管理だけです。Git のブランチ運用やソフト本体のリリース番号は開発会社の内部プロセスであり、発注側が細かく指定する必要はありません。一方、APIバージョン管理は「外部の誰かのシステムが動かなくなるかどうか」を左右するため、取り決めを文書に残す価値があります。

また、API と混同されやすい概念として OSS（オープンソースソフトウェア）があります。両者の位置づけの違いを確認したい場合は、OSSとAPIの違いを参照してください。

バージョニングがないAPIで何が起きるか

バージョンの区別がない API で仕様変更が行われると、利用側のシステムでは典型的に次のような事象が起きます。

• これまで取得できていた項目が突然なくなり、画面や帳票が空欄になる
• データの形式が変わり（例: 数値だったものが文字列になる）、集計処理がエラーで停止する
• 必須の入力項目が増え、これまで通りの送信内容がすべてエラーとして拒否される
• エラーになっていることに気づかないまま、データだけが欠落し続ける

やっかいなのは最後のパターンです。連携処理は夜間バッチで動いていることが多く、明確な障害画面が出ないため、月次の数値が合わないという形で数週間後に発覚することがあります。バージョニングは、この「気づかないうちに壊れる」状態を防ぐための仕組みでもあります。

API の設計指針を示した公式ドキュメントでも、同一メジャーバージョンの範囲では後方互換性を保ち、互換性を壊す変更を行う場合はメジャーバージョンを上げるという原則が示されています（Google API 設計ガイド「バージョニング」）。

APIバージョニングが必要になる2つの場面と放置したときのリスク

APIバージョニングの話をするとき、自社がどちらの立場にいるのかを最初に確定させると、必要な対応範囲が一気に絞り込めます。立場は「API を提供する側」と「API を利用する側」の二つで、取るべきアクションはまったく異なります。

提供する側の場面

自社のシステムが、取引先や関連会社、あるいは自社の別システムに向けて API を公開している場合が該当します。たとえば、卸売業の企業が取引先の小売店に在庫照会 API を提供しているケースです。

この立場で仕様を変更すると、影響は自社の外に及びます。取引先側にも改修作業と費用が発生するため、変更のタイミングを一方的に決めることができません。したがって、提供側に求められるのは技術的な実装よりも、「いつ告知し、どれくらいの移行期間を設け、誰にどう連絡するか」という段取りの設計です。ここが曖昧なまま仕様変更を進めると、取引先からのクレームや、最悪の場合は取引そのものの見直しにつながります。

利用する側の場面

会計 SaaS、CRM、EC プラットフォームなど、外部サービスの API を使って自社システムを連携させている場合が該当します。中堅企業の情報システム部門が直面する場面としては、こちらが圧倒的に多いはずです。

この立場の特徴は、スケジュールの主導権が相手側にあることです。提供元が「このバージョンは○年○月で終了します」と決めれば、利用側はその期限までに改修を終えるしかありません。交渉の余地はほとんどなく、できるのは「早く気づいて、余裕を持って動くこと」だけです。

したがって利用側のアクションは、廃止告知が届いてから慌てて対応するのではなく、平時から「自社がどの外部 API のどのバージョンを使っているか」を把握しておくことに尽きます。あわせて、API 利用時にはバージョン以外にも呼び出し回数の制限といった制約がかかることがあります。この点はAPI利用制限（レートリミット）の仕組みで整理しています。

バージョン方針を決めずに放置したときに発生するコスト

バージョニングの取り決めを後回しにした場合、コストは次の三つの形で顕在化します。

1. 予算外の緊急改修費

廃止告知を受けてから改修を始めると、通常の開発計画とは別枠での発注になります。期限が切られているため、スケジュールを詰めた体制を組むことになり、平時に計画的に実施する場合よりも単価・工数ともに膨らみやすくなります。年度予算が確定した後に告知が届けば、補正予算の申請という社内手続きも追加で発生します。

2. 連携停止による業務影響

改修が期限に間に合わなかった場合、連携は止まります。受注データが基幹システムに流れ込まなくなれば、手入力での運用でしのぐことになり、現場の工数と入力ミスのリスクが同時に増えます。

3. 現状把握そのものにかかる調査コスト

見落とされがちですが、これが最も読みにくいコストです。「どの外部 API のどのバージョンを、どの処理が呼んでいるか」が文書に残っていない場合、改修の前に棚卸し調査が必要になります。担当者が異動・退職していれば、当時の判断理由をたどる手段もありません。

秋霜堂株式会社でも、前任者が不在でドキュメントも残っていない既存システムについて、初期調査から改善対応までを継続的に実施した実績があります（出典: 秋霜堂株式会社の開発実績、事例ブログ掲載案件）。こうした状況では、改修に着手する前段階の「現状を把握する」工程そのものが独立した作業として必要になります。API のバージョン方針を発注時に文書化しておくことは、将来この調査コストを支払わずに済ませるための投資でもあります。

後方互換性と破壊的変更｜APIのバージョンを上げる判断基準

外部 API の変更通知を受け取ったとき、最初に判断すべきは「これは自社の改修が必要な変更か」です。この判断の軸になるのが、後方互換性という考え方です。

後方互換性のある変更と破壊的変更の具体例

後方互換性がある変更とは、既存の利用者がこれまで通りの呼び出し方を続けても、これまで通りの結果が得られる変更です。原則として自社の改修は不要です。

• レスポンスに新しい項目が追加される（既存の項目はそのまま残る）
• 任意入力のパラメータが追加される（指定しなくても従来通り動く）
• 新しいエンドポイントが追加される（既存のエンドポイントは変わらない）
• エラーメッセージの文言が改善される（エラーコードの体系は変わらない）

破壊的変更（Breaking Change）とは、これまで通りの呼び出し方では動かなくなる変更です。自社側の改修が必要になります。

• レスポンスから項目が削除される、または名称が変更される
• データの型が変わる（数値 → 文字列、単一の値 → 配列 など）
• これまで任意だったパラメータが必須になる
• エンドポイントの URL 構造が変わる
• 認証方式が変更される
• エラーコードの体系や意味が変わる

判断に迷いやすいのが「項目の追加」です。単純な追加であれば互換性は保たれますが、追加された項目が必須入力である場合は破壊的変更になります。通知文に「新しいパラメータを追加しました」とだけ書かれている場合、それが任意か必須かを確認する必要があります。

セマンティックバージョニング（MAJOR.MINOR.PATCH）の読み方

多くの API 提供元は、2.4.1 のような三つの数字でバージョンを表現します。これはセマンティックバージョニングと呼ばれる規約で、それぞれの数字が更新される条件が定められています（セマンティック バージョニング 2.0.0）。

発注側が覚えておくべきなのは一点だけです。一つ目の数字（MAJOR）が上がったという通知は、「自社の改修が必要かもしれない」というシグナルとして扱い、必ず開発会社に確認する。二つ目・三つ目の数字だけが変わっている通知は、原則として様子見で構いません。

ただし、これはあくまで規約であり、すべての API 提供元が厳密に従っているわけではありません。日付を使ったバージョン表記（後述の Shopify のように 2026-04 とするもの）を採用している提供元もあります。この場合は数字から互換性を読み取れないため、リリースノートの内容を確認する必要があります。

非エンジニアでも破壊的変更を見分けるチェック質問

技術的な判定を自分で行う必要はありません。変更通知を開発会社や社内の担当者に転送する際、次の質問を添えるだけで、判断に必要な情報が揃います。

1. この変更後も、今のシステムは改修なしでそのまま動きますか（最も重要な質問。ここが「はい」なら以降は確認不要）
2. 削除される項目や、名前が変わる項目はありますか
3. 新しく必須になる入力項目はありますか
4. データの形式（型）が変わる項目はありますか
5. 認証の方式やアクセス先の URL は変わりますか
6. 改修が必要な場合、影響する処理はどれくらいの範囲ですか（工数と費用の見積依頼につながる質問）
7. 改修しなかった場合、いつから何が動かなくなりますか（対応の優先度を決めるための質問）

この 7 問への回答が揃えば、「対応が必要か」「いつまでにやるか」「どれくらいの予算が要るか」という社内報告に必要な材料が一通り集まります。逆に、開発会社からの回答がこの粒度に達していない場合は、追加で確認を求めてください。

APIバージョニングの3方式（URL・ヘッダー・クエリパラメータ）を比較

API のバージョンを指定する方法には、主に三つの方式があります。どれを採用するかは通常、開発会社が設計判断として決めます。発注側が方式を指定する必要はありませんが、「なぜその方式を選んだのか」を説明してもらえる状態にしておくことは有益です。

URLパス方式（URLバージョニング）の特徴と向き不向き

URL の中にバージョン番号を含める方式です。最も広く使われています。

GET https://api.example.com/v1/orders
GET https://api.example.com/v2/orders

メリット: URL を見ただけでどのバージョンを呼んでいるかが分かります。ブラウザのアドレスバーに貼るだけで動作を確認でき、ドキュメントや障害時の問い合わせでも「v1 の方です」と口頭で伝えられます。取引先が多い場合、この分かりやすさは移行の周知コストを大きく下げます。

デメリット: バージョンが変わるとエンドポイントの URL 自体が変わるため、利用者側は接続先の設定変更が必要になります。また、v1 と v2 でリソースの内容が同じでも別の URL になるため、URL は同一のリソースを指すべきという設計思想の観点からは批判もあります。

向いている場面: 社外の取引先や不特定多数に公開する API。バージョンの違いを利用者に明確に意識させたい場合。

HTTPヘッダー方式（ヘッダーバージョニング）の特徴と向き不向き

リクエストのヘッダー（通信の付帯情報を格納する領域）でバージョンを指定する方式です。

GET https://api.example.com/orders
Accept: application/vnd.example.v2+json

メリット: URL が一つに保たれるため、リソースの位置とバージョンという別々の概念を混ぜずに済みます。利用者ごとに異なるバージョンを配信するといった細かい制御もしやすくなります。

デメリット: URL を見てもバージョンが分からないため、動作確認や障害調査の際にヘッダーの中身まで確認する必要があります。利用者側にも、ヘッダーを正しく設定するという一手間が生じます。ヘッダーを指定し忘れた場合にどのバージョンが返るのかを、あらかじめ決めておく必要もあります。

向いている場面: 社内システム間の連携や、利用者が限定されており技術的な習熟度が高い場合。

クエリパラメータ方式の特徴と向き不向き

URL の末尾に ?version=2 のような形式でバージョンを付ける方式です。

GET https://api.example.com/orders?version=2

メリット: 実装が簡単で、既存の API に後からバージョン指定を追加しやすい方式です。パラメータを省略した場合の既定バージョンを決めておけば、既存の利用者に影響を与えずに導入できます。

デメリット: 業務上の検索条件を指定するパラメータと、バージョンを指定するパラメータが同じ場所に混在するため、URL が読みにくくなります。指定漏れも起きやすく、大規模な API での採用例は多くありません。

向いている場面: 小規模な連携や、既存 API に段階的にバージョン管理を導入する過渡期。

3方式の比較表と選定の判断軸

発注側としての判断軸はシンプルです。取引先など社外の利用者が多く、移行の周知が必要になる API なら URL パス方式が無難です。社内システム間の連携で、バージョンごとの細かい制御を重視するならヘッダー方式が候補になります。

繰り返しになりますが、方式の選定は開発会社の設計判断であり、発注側が指定する必要はありません。確認すべきなのは「どの方式を採用したか」と「なぜその方式にしたか」の二点で、この説明が明快に返ってくるかどうかが、設計の妥当性を測る材料になります。

なお、複数のバージョンを並行して提供したり、利用者ごとに接続先を振り分けたりする仕組みは、API ゲートウェイと呼ばれる基盤で実現されることがあります。仕組みと費用の考え方はAPIゲートウェイの仕組みと設計判断で解説しています。

非推奨から廃止までのAPIバージョンのライフサイクル運用

「廃止までにどれくらいの猶予があるのか」は、発注側にとって最も実務的な関心事です。ここでは標準的な流れと、実際の提供元が設定している期間の実例を見ていきます。

非推奨（Deprecation）から提供停止（Decommission）までの流れ

API のバージョンは、いきなり停止されるわけではありません。通常は二段階の告知を経て終了します。

第一段階: 非推奨（Deprecation）

「このバージョンは今後、新機能の追加を行いません。新規に利用する場合は新しいバージョンを使ってください」という宣言です。この時点では API はまだ動きます。ここが重要な点で、非推奨の通知を受け取った時点で慌てて改修する必要はありません。ただし、この通知は「終了時期のカウントダウンが始まった」という合図です。

第二段階: 提供停止（Decommission / Retirement）

実際に API が停止される段階です。この日以降、旧バージョンへのリクエストはエラーになります。

利用側が非推奨の告知から提供停止までの間にやるべきことは、次の順序で整理できます。

1. 影響調査: そのバージョンを使っている自社の処理を洗い出す
2. 差分確認: 新バージョンとの間に破壊的変更がいくつあるかを開発会社に確認する
3. 改修計画と見積: 工数・費用・期間を確定させる
4. 予算確保: 社内の承認プロセスを通す（年度をまたぐ場合はここが最も時間を要します）
5. 改修とテスト: 実装と動作確認を行う
6. 切り替え: 新バージョンへ移行し、旧バージョンでの呼び出しが残っていないことを確認する

この 6 工程のうち、技術的な作業は 5 と 6 だけです。1 から 4 は発注側が主導する工程であり、ここに時間がかかることを前提にスケジュールを引く必要があります。

サポート期間の相場と廃止・移行スケジュールの実例

では、実際の猶予期間はどの程度なのでしょうか。主要な提供元の公表内容を見ると、目安が見えてきます。

Shopify（EC プラットフォーム）

3 か月ごと（四半期の初め）に新しい API バージョンをリリースし、各安定版を最低 12 か月間サポートしています。連続するバージョン間には最低 9 か月の重複期間が設けられており、利用者はその間に移行作業を行えます（Shopify 公式ドキュメント: API versioning）。

Azure API Management（Microsoft）

2021-08-01 より前の API バージョンの提供終了について、当初は 2023 年 9 月 30 日を予定していましたが、その後 2024 年 6 月 1 日へと延期されました（Microsoft Learn: Azure API Management - API バージョンの提供終了）。告知から実施まで、結果として 1 年半以上のリードタイムが確保されたことになります。

Salesforce（CRM）

Platform API バージョン 21.0〜30.0 の廃止は、当初 Summer '23 での実施が予定されていましたが延期され、最終的に Summer '25（Sandbox は 2025 年 5 月、本番環境は 2025 年 6 月）での実施となりました（Salesforce リリースノート: Salesforce Platform API Versions 21.0 T…、Salesforce サクセスナビ: Platform API バージョン 21.0 〜 30.0 の廃止）。レガシー API の廃止計画そのものは 2021 年にアナウンスされており、告知から実施まで数年の猶予が与えられた事例です。

これらの実例から読み取れる相場観は次のとおりです。

• サポート期間の目安は最低 1 年、実際には 1 年半〜数年におよぶことも多い
• 大手の提供元ほど、利用者の準備状況を見て延期する傾向がある
• ただし、延期を前提に動くのは危険です。延期は提供元の裁量であり、予告されるものではありません

発注側としての現実的な目安は、「非推奨の告知を受けたら、その時点から予算計上の準備を始め、遅くとも提供停止の 6 か月前には改修に着手できる状態にしておく」ことです。年度予算のサイクルを考えると、告知を受けた年度内に見積を取得し、翌年度の予算に組み込むという流れが最も現実的でしょう。

利用者への通知・移行ガイド・利用状況モニタリング

自社が API を提供する側の場合、ライフサイクル運用として次の三点をセットで設計する必要があります。

1. 通知の設計

「誰に、いつ、どの手段で伝えるか」を決めます。メール配信のほか、API のレスポンスヘッダーに非推奨を示す情報を付与する方法もあります。取引先の担当者は変わることがあるため、単発のメール送信だけに頼るのは避けたほうが安全です。

2. 移行ガイドの提供

新旧バージョンの差分を一覧化した資料を用意します。「どの項目がどう変わったか」「移行に必要な作業は何か」を利用者側の目線でまとめておくと、問い合わせ対応の工数を大幅に削減できます。

3. 利用状況のモニタリング

旧バージョンが実際にどれだけ呼ばれているかを計測します。提供停止の予定日が近づいた時点で呼び出しが残っていれば、その利用者に個別に連絡できます。この計測の仕組みがないと、停止した瞬間に初めて影響先が判明するという事態になります。

この三点は、いずれも「実装」ではなく「運用の仕組み」です。開発の見積に含まれているかどうかを確認しておくべき項目でもあります。

APIバージョニングについて発注時に確認すべき7つの項目

ここまでの内容を、発注実務で使える形に落とし込みます。確認項目は、要件定義・見積の段階で確認する 4 項目と、保守・運用契約に織り込む 3 項目に分かれます。

要件定義・見積段階で確認する4項目

項目 1: バージョニング方式と、その方式を選んだ理由

採用する方式（URL パス／ヘッダー／クエリパラメータ）と選定理由を、設計書に明記してもらいます。理由の説明が「一般的だから」で終わる場合は、自社の利用形態（社外公開か社内連携か、利用者数はどれくらいか）を踏まえた説明を求めてください。

項目 2: 同時にサポートするバージョンの数と、その維持期間

「新旧 2 バージョンを並行提供し、旧バージョンは新バージョンのリリースから 12 か月間維持する」といった形で、数と期間を決めます。この取り決めが将来の保守コストを規定するため、口頭ではなく文書に残すことが重要です。バージョンを無制限に増やすと保守対象が膨らみ続けるため、上限を設けるのが一般的です。

項目 3: 連携先 SaaS の現在の API バージョンと廃止予定

自社システムが利用する外部 API について、「現在どのバージョンを使うのか」「そのバージョンの提供終了予定はいつか」を一覧化してもらいます。開発時点で既に非推奨になっているバージョンを採用してしまうと、稼働開始の直後に改修が必要になります。この確認は発注時にしか行えないため、優先度の高い項目です。

項目 4: 破壊的変更が起きたときの検知方法

外部 API に仕様変更があったことを、どうやって知るかを決めます。提供元のリリースノートを定期的に確認する運用にするのか、通知メールの受信先を情報システム部門の共有アドレスにするのか、あるいは連携処理のエラーを監視して異常を検知する仕組みを入れるのか。担当者の異動があっても機能する形にしておく必要があります。

API 連携の発注全般について、バージョニング以外の確認項目も含めて整理したい場合は、API連携を発注する際のチェックポイントもあわせてご覧ください。

保守・運用契約に織り込む3項目

項目 5: 外部 API の仕様変更への追従が、保守範囲に含まれるか

保守契約書に「外部 API のバージョン変更に伴う改修」が含まれるかどうかを確認します。「障害対応」「軽微な修正」といった表現だけでは、外部要因による改修が含まれるかは読み取れません。含まれる／含まれないのどちらであっても構いませんが、どちらなのかが明確になっていることが重要です。曖昧なまま運用に入ると、実際に告知が届いたときに追加費用の交渉から始めることになります。

項目 6: 追従作業が発生した場合の費用の扱い

保守範囲外とする場合、その作業をどう見積り、どう発注するかを事前に決めます。契約形態によって扱いは変わります。たとえば準委任型の月額契約であれば、契約を継続していれば追加の見積を発生させずにスケジュール内で対応する運用も可能です。実際に、秋霜堂が提供する開発サービス TechBand では、仕様変更が生じた場合のスコープ調整をスケジュールで吸収し、追加見積もりを発生させない運用としています（出典: 秋霜堂株式会社 TechBand の公開 FAQ）。一方、請負型の契約であれば、追従作業は都度の個別発注になるのが通常です。どちらが優れているという話ではなく、自社の予算管理の仕方に合う形を選ぶことが判断軸になります。

項目 7: 緊急改修が必要になった場合の対応条件

提供停止の期限が迫った状態で改修が必要になった場合に、どの程度の速度で対応してもらえるかを確認します。着手までの期間、優先度の扱い、通常時と異なる費用が発生するかどうかが論点です。リリース後の修正に応じられる契約形態かどうかも、あわせて確認しておくとよいでしょう。月額制の準委任型契約であれば、契約を継続または延長することでリリース後の修正に対応できる設計もあります（出典: 秋霜堂株式会社 TechBand の公開 FAQ）。

開発会社にそのまま使える確認質問リスト

上記 7 項目を、打ち合わせやメールでそのまま使える質問文の形にまとめました。

要件定義・見積段階

• 「API のバージョン指定は、URL・ヘッダー・クエリパラメータのどの方式を採用する予定でしょうか。また、その方式を選んだ理由を教えてください」
• 「同時にサポートするバージョンは何世代までを想定していますか。旧バージョンはどれくらいの期間、維持する設計でしょうか」
• 「今回連携する外部 API について、使用するバージョンと、そのバージョンの提供終了予定を一覧でいただけますか」
• 「連携先の API に仕様変更があった場合、当社側はどうやってそれを知ることになりますか。検知の仕組みは組み込まれますか」

保守・運用契約段階

• 「外部 API のバージョン変更に伴う改修は、保守契約の範囲に含まれますか。含まれる場合、その旨を契約書のどの条項で読めばよいか教えてください」
• 「保守範囲外の場合、追従作業の費用はどのように算定されますか。契約形態によって扱いが変わるようであれば、選択肢を示していただけますか」
• 「提供終了の期限が迫った状態で改修が必要になった場合、着手までにどれくらいの期間が必要でしょうか。通常時と異なる条件が適用されますか」

これらの質問への回答を書面で受け取り、要件定義書・見積書・保守契約書のいずれかに反映させておけば、将来の廃止告知に対して「取り決め済みの手順に従って動く」だけで済みます。

まとめ｜APIバージョニングは発注段階で決まる将来の改修コスト

APIバージョニングは、同じ API の複数バージョンを並行提供することで、利用側が自分たちのタイミングで移行できるようにする仕組みです。発注する立場で押さえるべき論点は、次の四点に集約されます。

• 破壊的変更かどうかの見分け方: 項目の削除・型変更・必須化・URL 構造の変更は改修が必要。セマンティックバージョニングの一つ目の数字（MAJOR）が上がったら要確認
• 3 方式の違い: 社外公開なら URL パス方式、社内連携ならヘッダー方式が目安。方式そのものより「なぜその方式か」の説明を確認する
• 猶予期間の相場: サポート期間の目安は最低 1 年、実際には 1 年半〜数年のこともある。ただし延期を前提にしない
• 発注時の確認項目: 要件定義・見積で 4 項目、保守・運用契約で 3 項目を文書に残す

これらの取り決めを後回しにすると、廃止告知が届いた時点で、予算にも計画にも入っていない緊急改修に着手することになります。逆に、発注段階で数行の取り決めを文書に残しておけば、同じ事象が「想定内の定期作業」に変わります。APIバージョニングにかかるコストは、技術の問題ではなく、いつ意思決定するかの問題です。

最初のアクションとして推奨したいのは、現在自社が連携しているすべての外部 API について、使用中のバージョンと提供終了予定を一覧化することです。連携先のサービス名、API のバージョン、提供終了の予定日（未定なら「未定」）、担当している開発会社。この 4 列の表を作るだけで、次に何が起きるかが見えるようになります。開発会社に依頼すれば、既存システムであっても半日から数日で整理できる範囲の作業です。

関連情報

システム開発の見積内訳や費用の妥当性を判断する考え方については、お役立ち資料「システム開発費用ガイド」で整理しています。保守フェーズを含めた費用構造を確認したい方はご覧ください。

外部システムとの API 連携や、既存連携の改修についてご検討中の方は、お問い合わせフォームからご相談ください。要件が固まっていない段階でのご相談にも対応しています。

—Free Download / 資料ダウンロード

システム開発 完全チェックリスト――発注前・発注中・完了後の3フェーズで使えるチェック集

この資料でわかること

システム開発の外注・発注を初めて経験する担当者や、過去に失敗を経験した担当者が、発注プロセスの各フェーズで「何をチェックすべきか」を明確に把握できるようにする。

こんな方におすすめです

• 初めてシステム開発を外注する担当者
• 過去の発注で失敗を経験した方
• ベンダー選定の基準が分からない方

詳しく見る

フォームから無料ダウンロード

お名前必須

会社名必須

メールアドレス必須

電話番号任意

ご質問・ご要望任意

プライバシーポリシーに同意の上、送信します。

ダウンロードする

入力いただいたメールアドレスにPDFをお送りします。