APIとは?「機能を外から呼べるようにした窓口」——REST・GraphQL・SOAPの違いから、認証・レート制限・仕様変更まで発注者目線で解説【2026年版】

「提案書に『既存システムとAPI連携します』と書いてあるのですが、これは何をする作業なんでしょうか」——システム開発を発注する立場の方から、こうした相談をよく受けます。検索すると、レストランで注文を取り次ぐ店員の絵が出てきます。言いたいことは分かる。でも、片方が連携部分に180万円と書き、もう片方が「別途お見積もり」としか書かない理由までは分かりません。比喩の先が知りたい。そういう方は少なくありません。

先に答えを書きます。APIとは、ソフトウェアが持つ機能やデータを、外から決まった手順で呼び出せるようにした窓口のことです。窓口という言い方には理由があります。窓口には様式があり、受付時間があり、本人確認があり、ある日「この用紙は来年3月で廃止します」と貼り紙が出ます。APIも同じで、呼び出しの形、1日に呼べる回数、認証の方法、仕様の変更予告が、すべて相手側の都合で決まります。

だから、発注者が押さえるべきは一点、つながることよりも、つながった後に何が起きるかです。HTTPには「呼びすぎです」を伝える専用のコード(429)があり、「この機能は非推奨になりました」を伝える取り決めも標準化されています。相手の都合で壊れることは、例外ではなく織り込み済み。見積書に「API連携 一式」としかない案件が後で揉めるのは、この織り込みが金額の前提として共有されていないからです。

本記事では、APIの定義とWeb APIおよびそれ以外の区別、1回のやり取りで行き来するもの(エンドポイント・HTTPメソッド・ステータスコード・JSON)、REST・GraphQL・SOAPの違いとSDK、認証・レート制限・バージョニング、外部サービス連携で決まること、止まるリスクと発注側が握る3つ、の順に解説します。個別サービスのAPI詳細、BaaS、マイクロサービス、フロントとバックの役割分担は既存の記事に譲ります。定義はMDN、RFC、W3C、OpenAPI Initiative、GraphQL公式仕様などの一次情報を2026年9月19日に直接確認した範囲だけを書きます。コードも書きません。実装する人ではなく、発注して判断する人のための記事です。

私は人材業界の出身で、2018年からホーチミンでベトナムオフショア開発の体制づくりに携わり、約100社の相談に乗ってきました。当社の案件にも、決済サービスと連携するアプリや、外部のLLMを呼び出して24時間動くチャットボットがあります。この種の案件で最初に確認するのはコードではありません。連携先の仕様書がどこにあるのか、誰のアカウントで認証するのか、相手が仕様を変えたときの改修は誰が持つのか——この3つです。ここが白紙のまま進んだ案件は、連携そのものより後工程で費用が動きます。読み終えるころには、開発会社に何を聞くべきかが決まっているはずです。

APIとは——ソフトウェアの機能を、外から決まった手順で呼べるようにした「窓口」

APIとは、あるソフトウェアが持っている機能やデータを、外から決まった手順で呼び出せるようにした窓口のことです。Application Programming Interface の頭文字を取った語です。比喩を使うなら窓口がいちばん近いのですが、比喩はここまでにして、実体を見ていきます。窓口という言い方にこだわる理由は、この章の最後で分かるはずです。

APIの定義——「提供する側と使う側のあいだの契約」

Web技術の標準的なリファレンスであるMDN Web Docsは、APIを「ソフトウェアプログラム(アプリケーション)の内部に存在する機能とルールの集合であり、人間向けのユーザーインターフェースとは対照的に、ソフトウェアを通じてそのプログラムとやり取りできるようにするもの」と説明しています。そのうえで「APIは、提供するアプリケーションと、サードパーティのソフトウェアやハードウェアといった他のものとのあいだの、単純な契約(インターフェース)とみなすことができる」と続けます(2026年9月19日確認)。

注目すべきは契約という語です。窓口で扱える手続きの種類、必要な書類、本人確認の方法は、窓口を開いている側が決めます。利用する側はそれに合わせるしかありません。この非対称性が、後半で扱う認証・回数制限・仕様変更の話すべてにつながっていきます。

もうひとつ、定義から外れないでほしい点があります。APIは「つなぐ道具」ではなく「呼び出し口そのもの」です。日本語で「API連携」と言うとき、実際に起きているのは、自社のシステムが相手のシステムの窓口に対して、決められた形式で用件を出し、決められた形式で答えを受け取る、という動作の繰り返しです。連携という言葉が持つ「双方向で対等」という語感とは、少し違います。

Web APIと、それ以外のAPI——ブラウザ・OS・ライブラリにもAPIがある

「APIとは」と検索する人の多くが思い浮かべているのは、インターネット越しに他社のサービスを呼ぶ形式、つまりWeb APIです。ただし定義上、APIはそれだけではありません。

MDNが公開しているWeb APIの一覧には、位置情報を扱うGeolocation API、通信を行うFetch API、端末側にデータを保存するWeb Storage API、暗号処理のWeb Crypto APIなど、200を超えるAPI仕様が収録されています(2026年9月19日確認)。「カメラを使う許可を求めてきたアプリ」も、技術的にはAPIの呼び出しです。

つまりAPIという語は、ネットワーク越しの連携よりずっと広い範囲を指します。本記事はこのうちWeb APIを中心に扱いますが、提案書に「ブラウザのAPIで位置情報を取得」と書いてあった場合、それは他社との連携ではなく端末機能の利用だという区別は持っておくと、話が早くなります。なお、画面側とサーバー側で仕事がどう分かれるのかについては、『フロントエンドとバックエンドの違い』の記事にまとめてあります。

公開API・パートナーAPI・社内API——誰に窓口を開けるかの3区分

窓口である以上、「誰に開けるか」という区分が存在します。実務では次の3つで整理すると話が通じます。

この区分が効いてくるのは、自社がAPIを提供する側に回る場面です。社内APIなら、仕様を変えたいときに関係者へ声をかければ済みます。公開APIにした瞬間、誰が使っているか把握できないまま、変更のたびに告知と移行期間が必要になる。外部サービスの機能をまとめて借りる形態については『BaaSとは』、記事コンテンツをAPI経由で配信する仕組みについては『microCMSとは』の記事で個別に扱っています。

ここまでが語義です。以降はWeb APIを中心に、実際に何が行き来しているのかを見ていきます。窓口の様式を知らないまま発注すると、見積書の数字が読めないままになるからです。

1回のやり取りで何が行き来するのか——エンドポイント、メソッド、ステータスコード、JSON

APIの呼び出しは、1回につき往復1セットです。こちらから用件を送り(リクエスト)、相手から答えが返る(レスポンス)。この往復で行き来するものは、リクエスト側が4つ、レスポンス側が2つしかありません。名前を覚える必要はありませんが、何が決まっていないと呼び出せないのかを知っておくと、見積書の項目が読めるようになります。

リクエストに乗せる4つ——URL、メソッド、ヘッダー(認証)、パラメータ

送る側が用意するのは次の4つです。

1. URL(エンドポイント)——どの窓口に出すか。https://api.例.com/v1/orders のような形で、末尾が扱う対象を表します
2. メソッド——何をしたいか。取得なのか、登録なのか、削除なのかを1語で示します
3. ヘッダー——本人確認とデータ形式の申告。APIキーやトークンはここに入ります
4. パラメータ——条件。「2026年9月分だけ」「1回に100件まで」といった絞り込み

このうち発注者の話に直結するのがメソッドです。HTTPで使えるメソッドは決まっており、MDNは次のように整理しています(2026年9月19日確認)。

表の右2列が実務で効きます。冪等とは、同じ呼び出しを2回3回と繰り返しても結果が変わらない性質のことです。通信が途中で切れて成功したのか失敗したのか分からないとき、冪等な呼び出しならもう一度送れば済みます。POSTは冪等ではないため、そのまま再送すると二重登録が起きる。「通信が不安定だったときに注文が2件入る」という事故は、ここから生まれます。連携の見積もりに「再送制御」「重複排除」といった項目があれば、それはこの性質への対処です。

レスポンスで返る2つ——ステータスコードと、本体(JSON)

返ってくるものは2つです。まずステータスコード。3桁の数字で、最初の1桁が結果の種類を表します。HTTPの意味論を定めたRFC 9110(STD 97・2022年6月)は、5つの区分を次のように定義しています。

覚えておくと会話が早いのは4つです。400は出し方の不備、401は本人確認の失敗(鍵が違う、期限切れ)、404は指定した対象が見つからない、500は相手側の内部エラー。障害の連絡を受けたとき、4xxなのか5xxなのかで、直す当事者が変わります。相手が5xxを返している最中に自社の開発チームを深夜に呼び出しても、できることはありません。

もうひとつが本体です。現在のWeb APIではJSONという形式が主流で、RFC 8259(2017年12月)が「軽量でテキストベース、言語非依存のデータ交換形式」と定義し、application/json というメディアタイプを登録しています。後述するSOAPではXMLが使われます。形式が違っても、発注者にとっての意味は同じ——表形式で受け取れるか、入れ子の構造で受け取るかの違いです。

発注者が知っておくと得をする点——「1回で何件取れるか」が工数を決める

ここが見積もりに直結します。たとえば顧客データ1万件を同期したいとき、相手のAPIが1回の呼び出しで100件しか返さない仕様なら、100回呼ぶ処理を書く必要があります。件数の上限、次のページを取りにいく方法、途中で失敗したときの再開位置——この3つを扱う作りを、開発の現場ではページネーション処理と呼びます。「連携するだけなのに、なぜこんなに工数がかかるのか」と感じる案件の多くは、ここに時間が入っています。

したがって、提案を受けたら1つだけ聞いてみてください。「相手のAPIは1回で何件返しますか。全件同期するのに何回呼ぶ想定ですか」。この質問に即答できる開発会社は、相手の仕様書を実際に読んでいます。読まずに「一式」と書いた見積もりとは、そこで差が出ます。

REST・GraphQL・SOAPの違い——発注者が判断に使える粒度で

提案書に「REST APIで連携します」と書いてあるとき、それは通信の作法を1つ選んだという意味です。作法には主に3つあり、それぞれ生まれた時期も設計思想も違います。ただし先に結論を書いておくと、多くの案件で作法は選べません。相手のサービスが提供している形に合わせるしかないからです。連携先がすでに決まっている方は、この章は流し読みで構いません。

REST——2000年の博士論文で定義された「設計様式」。規格ではない

RESTは規格でも製品でもありません。Roy Thomas Fielding氏が2000年にカリフォルニア大学アーバイン校へ提出した博士論文の第5章「Representational State Transfer (REST)」で定義された、ネットワーク上のソフトウェアの設計様式です(2026年9月19日に原典を確認)。論文はRESTを「第3章で述べたネットワークベースのアーキテクチャスタイルのいくつかから派生した混成のスタイルであり、統一されたコネクタインターフェースを定義する追加の制約を組み合わせたもの」と説明しています。

そこで示されている制約は6つ——クライアント・サーバー、ステートレス、キャッシュ、統一インターフェース、階層化システム、コードオンデマンドです。このうち論文が「RESTを他のネットワークベースのスタイルから区別する中心的な特徴」と呼んでいるのが統一インターフェース、つまり対象をURLで指し、操作をHTTPメソッドで表すという約束です。

発注者にとって意味があるのは次の点です。RESTは様式であって検査に通る規格ではないため、「REST API」と名乗っていても作りには幅があります。実際、世の中のREST APIの多くは6つの制約をすべて満たしてはいません。したがって「RESTだから安心」という判断は成り立たず、確認すべきはやはり相手の仕様書の中身になります。

GraphQLとSOAP——欲しい形で問い合わせる方式と、XMLの封筒

GraphQLは、公式仕様(September 2025版・2025年9月3日公開)が「クライアント・サーバーアプリケーションのデータモデルの能力と要件を記述し実行するための、クエリ言語および実行エンジン」と定義しているものです。操作の型は3つ——query(読み取り)、mutation(書き込みとその後の読み取り)、subscription(継続的な購読)。仕様はGraphQL Specification Projectの成果物として、Joint Development FoundationのもとでOWFa 1.0ライセンスで公開されています(2026年9月19日確認)。

RESTとの違いを発注者の言葉にすると、「窓口ごとに決まった様式の答えが返る」のがREST、「欲しい項目を書いて出すと、その形で返る」のがGraphQLです。画面によって必要な項目が大きく変わるアプリで、通信量と呼び出し回数を減らせます。

SOAPは、W3Cが勧告として公開している仕様(SOAP Version 1.2 Part 1: Messaging Framework 第2版・2007年4月27日)に基づく、XMLを使った通信の枠組みです。仕様はSOAPを「分散環境で構造化された情報を交換するための軽量なプロトコル」と説明し、メッセージはEnvelope(封筒)、Header、Bodyという入れ子のXMLで構成されます。なお同仕様には「以前の版ではSOAPという名称は頭字語だったが、現在はそうではない」という記述があります。つまりSOAPはもう何かの略ではありません。

SDKとAPIの関係——SDKは「APIを使いやすく包んだもの」

見積書にSDKという語が出てくることがあります。Software Development Kit の略で、そのAPIを特定のプログラミング言語から呼びやすくするために、提供側が用意した部品一式です。APIが窓口なら、SDKは窓口用の記入済み申請書とペンのセットに当たります。

発注者が知っておくべき点は2つ。第一に、SDKがあると実装は速くなりますが、SDKそのものにもバージョンがあり、相手がAPIを変えればSDKも更新されます。更新に追従する作業は残ります。第二に、使いたい言語のSDKが提供されていない場合、開発会社はAPIを直接呼ぶ実装を書くことになり、その分の工数が乗ります。提案を比べるときは、SDKを使う前提か、直接呼ぶ前提かを確認すると、金額差の説明がつくことがあります。

作法の話は以上です。繰り返しになりますが、選べる場面は多くありません。複数のサービスに分けて作る設計そのものについては『マイクロサービスとは』の記事が扱っています。GraphQLを含む複数の配信方式を持つヘッドレスCMSの例は『Contentfulとは』の記事で個別に整理しました。発注者が時間を使うべきは作法の比較ではなく、次章の3点です。

つながった後に効く3つ——認証、レート制限、バージョンと破壊的変更

APIの案件で費用と責任がもつれるのは、つなぐ工程ではなく、つないだ後です。相手は自社の都合で認証方式を変え、呼び出せる回数に上限を設け、ある日「この版は終了します」と告知します。いずれも思いつきではなく、標準として取り決めが存在する領域です。取り決めがあるということは、発注者の側から確認できるということでもあります。

認証——APIキーとOAuth 2.0。発注時に確認するのは「誰の権限で呼ぶか」

窓口には本人確認があります。方式は複数ありますが、API記述の標準であるOpenAPI Specificationは、セキュリティ方式として5種類を定めています——apiKey、http、mutualTLS、oauth2、openIdConnect(2026年9月19日確認)。発注の場で話題になるのは、ほぼ前半の2つと oauth2 です。

APIキーは、発行された文字列を毎回添えて送る方式です。OpenAPIはこのキーの置き場所として query(URLの末尾)、header(見出し部分)、cookie の3つを定義しています。単純で導入が速い反面、キーそのものが鍵なので、漏れればそのまま使われます。キーをソースコードに直接書いた状態でリポジトリに上げてしまうのは、いまだによくある事故です。

OAuth 2.0は、RFC 6749(2012年10月・標準化過程)が定める認可の枠組みです。仕様の要旨は「第三者のアプリケーションが、HTTPサービスに対して限定的なアクセスを取得できるようにする」こと。登場人物は4つ——リソースオーナー(本人)、リソースサーバー(データを持つ側)、クライアント(呼び出すアプリ)、認可サーバー(許可を出す側)。許可の与え方も4種類が定義されています(認可コード、インプリシット、リソースオーナーパスワードクレデンシャル、クライアントクレデンシャル)。

発注者が確認すべきは、方式名そのものではありません。誰の権限で呼ぶのかです。社内システムが会社の代表アカウントで呼ぶのか、利用者ひとりひとりが自分のアカウントで許可を出すのか。前者なら、そのアカウントが止まった瞬間に全社の連携が止まります。後者なら、利用者が許可を取り消したときの挙動を作り込む必要があります。あわせて、鍵を誰が保管し、退職時に誰が差し替えるのかも決めておく。外注時の情報の扱い全般は『オフショア開発のセキュリティ対策』の記事にまとめてあります。

レート制限——呼びすぎには専用のステータスコードがある

APIには「1分あたり何回まで」「1日あたり何件まで」という上限が設けられているのが普通です。上限を超えたときに返る専用のコードがあり、RFC 6585(2012年4月)は429 Too Many Requests を「所定の時間内に多すぎるリクエストを送った(レート制限)ことを示す」と定義しています。同仕様は、応答に Retry-After という見出しを付けて次に呼んでよい時刻を伝えてもよいとしています。

さらに、残りの呼び出し可能回数を伝えるための見出しを標準化する作業がIETFで進んでいます(draft-ietf-httpapi-ratelimit-headers-11・2026年5月23日時点。RFCとしては未発行)。RateLimit-Policy が割り当ての方針を、RateLimit が現在の残量を伝える設計です。まだ草案なので、実際の各サービスの伝え方はばらばらです。

発注の場面でこれが効くのは、初回の一括取り込みです。既存データ10万件を連携先へ流し込む場面で上限が1分100回なら、単純計算で丸1日近くかかります。「移行作業に3日」という見積もりが出てきたとき、その大半が待ち時間である可能性があります。生成AIのAPIのように呼び出し量がそのまま費用になる領域については、『生成AIアプリ開発』の記事で費用設計を扱っています。

バージョニングと破壊的変更——「壊さずに変える」ための約束事

最後が変更です。APIは一度公開したら終わりではなく、機能追加や仕様変更が続きます。このとき、使っている側を壊さずに変えるための考え方がバージョニングです。広く使われているセマンティックバージョニング2.0.0は、「APIの変更に互換性のない場合はメジャーバージョンを、後方互換性があり機能性を追加した場合はマイナーバージョンを、後方互換性を伴うバグ修正をした場合はパッチバージョンを上げる」と定めています(2026年9月19日確認)。URLに /v1/ /v2/ と入っているのは、この考え方が形になったものです。

互換性のない変更を破壊的変更と呼びます。項目名が変わる、必須項目が増える、返る形が変わる。いずれも呼び出し側の改修が要ります。そこで、廃止を事前に伝えるための仕組みも標準化されました。RFC 9745(2025年3月・標準化過程)が定める Deprecation という応答の見出しは、「あるリソースが非推奨になる予定である、または既に非推奨になったことを、利用者に伝えるために使う」ものです。同RFCは、実際に応答しなくなる日を示す Sunset(RFC 8594)と併用でき、Sunsetの日時はDeprecationの日時より前であってはならないと定めています。

つまり、いきなり止まるのではなく、非推奨の告知 → 移行期間 → 停止、という順序が想定されています。ただしこれは提供側がそう運用した場合の話です。告知は出ているのに、受け取る側が読んでいないために当日まで気づかない——実務で起きるのはこちらのほうが多いというのが実情です。仕様変更は事故ではなく、最初から織り込まれた前提。だからこそ、告知を読む担当を決めておくかどうかで結果が変わります。

「外部サービスと連携したい」と言ったとき、実際に決まること

ここからが発注者の実務です。会議で「あの会計ソフトと連携したい」と一言発した瞬間から、実は6つの項目が決まりにいきます。決まらないまま見積もりを出すと「API連携 一式」という行が生まれ、後から追加費用の話になる。私は2018年からホーチミンで約100社の開発体制を支援してきましたが、連携まわりで揉める案件のほとんどは、技術ではなくこの6項目の空白が原因でした。

連携の話が始まったら決める6項目

このうち3番と6番は、相手に申し込まないと手に入らないものです。発注側が動かないと開発会社は着手できません。見積もりをもらう前に、連携先のWebサイトで「開発者向け」「API」というページを探し、仕様書が公開されているかだけでも確認しておくと、話がひとつ前に進みます。決済サービスの導入における方式選択と費用の内訳は、『Stripe決済の導入と手数料』の記事で個別に扱っています。

連携先にAPIがない場合の代替——壊れやすさの順に4つ

相手にAPIがない、という事態はよくあります。そのときの代替は4つあり、壊れやすさが明確に違います。上から順に検討するのが筋です。

1. 提供元にAPIの提供を依頼する——最も確実です。要望が複数社から出ている機能であれば、ロードマップに入る可能性があります。時間はかかりますが、交渉のコストだけで済みます
2. ファイル連携(CSVなど)——決まった場所に決まった形式のファイルを置き、定期的に取り込む方式。古典的ですが壊れにくく、相手の画面が変わっても影響を受けません。欠点は、即時性がないことと、失敗に気づきにくいこと
3. ワークフロー自動化ツールを挟む——サービス間の連携をつなぐ道具を使う方法です。開発量は減りますが、ツール自体の料金と、ツールが対応していない操作は実現できないという制約が付きます。この種のツールの考え方は『n8nとは』の記事にまとめてあります
4. 画面操作の自動化(RPAなど)——人がブラウザで行う操作を機械に再現させる方式。最後の手段です。相手がボタンの位置を1つ変えた日に止まりますし、利用規約で自動操作を禁じている場合もあります。採用するなら、止まる前提で監視と代替手順を用意しておく

4番を「安い案」として提案された場合は要注意です。初期費用は安く見えますが、壊れたときに直すのは毎回こちら側で、その費用は見積もりに入っていないことが多いからです。

自社がAPI提供側になる場合に決めること

逆の立場、つまり自社のサービスに「APIはありますか」と問い合わせが来ている場合です。提供側になると、決めることは5つに増えます。

• 誰に開けるか——社内だけか、契約した相手だけか、登録すれば誰でもか。前章の3区分です
• 認証の方式——APIキーで足りるか、利用者ごとの許可が要るか
• 上限——1分あたり、1日あたり、何回までを許すか。ここを決めないと、1社の実装ミスで全体が遅くなります
• バージョン方針——変えたいときにどう告知し、旧版をいつまで維持するか
• サポートの窓口——問い合わせを誰が受けるか。ここが空白だと、開発チームが常時割り込みを受けます

経営の言葉に直せば、公開APIにするとは「その形を当面変えないと約束すること」です。社内APIなら関係者に声をかければ変えられますが、公開した瞬間、誰が使っているか把握できないまま変更のたびに移行期間が必要になります。まず社内APIやパートナーAPIから始めて、需要を見てから公開範囲を広げる——この順序をとる企業が多いのは、この非対称性があるからです。

API仕様書(OpenAPI)は納品物に含まれるか

自社がAPIを作る場合も、外部APIを呼ぶ処理を作る場合も、後で効いてくるのが仕様書が残るかどうかです。

APIの仕様を書き表す標準として、OpenAPI Specificationがあります。OpenAPI Initiative(The Linux Foundation)が公開しているもので、仕様自身が「HTTP APIのための、標準的でプログラミング言語に依存しないインターフェース記述を定義し、人間とコンピュータの双方が、ソースコードや追加のドキュメント、通信の観察なしにサービスの能力を発見し理解できるようにするもの」と説明しています。最新版は3.2.1(2026年9月10日公開・2026年9月19日確認)。かつてSwaggerと呼ばれていた仕様がこれにあたります。

発注者として確認すべき点は、技術的な良し悪しではありません。契約書または発注書の納品物一覧に、API仕様書が1行として入っているかです。入っていなければ、次の開発会社に引き継ぐときも、自社で保守に回るときも、コードを読み解くところから始めることになります。当社では、日本人PMの設計レビューとGitのプルリクエストによるコードレビューを標準の工程に組み込み、仕様と変更の履歴が残る形をとっています。仕様書全般の粒度と書き方については、『オフショア開発の仕様書の書き方』の記事で詳しく扱っています。

いま手元にある提案書で、上の6項目のうち何個が文字になっているでしょうか。3個以下なら、金額の議論より先に、埋める作業をおすすめします。

外部APIの仕様変更や停止で自社システムが止まるリスクと、発注側が握る3つ——当社の位置づけ

外部APIは自社の資産ではありません。サーバーを増やしても、コードを直しても、相手が変えると決めたものは変わります。この構造を前提に置くと、やるべきことは「壊れないようにする」ではなく「壊れたときに誰がどう動くかを先に決めておく」に変わります。ここが、API連携を含む開発を外部チームに任せるときの分かれ目です。

止まり方は3通り——変わる、止まる、遅くなる

3つのうち、実務でいちばん多いのは1番目です。そして厄介なのは、告知は出ていたのに読む人がいなかったという形で顕在化することです。外部APIの告知メールが、退職した担当者のアドレスにだけ届いていた——この手の話は珍しくありません。サーバー側の障害への向き合い方全般は『サーバー障害の原因と対応』の記事に、仕様変更が追加費用になる線引きは『仕様変更の追加費用はどこからか』の記事にまとめてあります。

発注側が握る3つ——連携先の仕様、障害時の扱い、仕様書の納品

開発そのものを外部チームに任せる場合でも、次の3つは発注側が握っておくべきものです。技術ではなく取り決めの話なので、非エンジニアでも判断できます。

1. 連携先の仕様——相手の仕様書の所在、試験環境の有無、アカウントの名義。ここが開発会社の名義のままだと、会社を替えるときに鍵ごと引き継げません。契約は自社名義で結び、開発会社には権限を貸す形が原則です
2. 障害時の扱い——4xxなのか5xxなのかで当事者が変わる、という話を前章で書きました。これを契約に落とすと、「一次対応は誰が何分以内に行うか」「相手側の障害が原因の停止は保守の範囲に含むか」という条項になります。24時間の対応を約束する契約かどうかも、ここで決まります
3. 仕様書の納品——API仕様書(OpenAPI形式など)と、連携処理の設計書を納品物一覧に明記すること。ここが1行あるかないかで、2年後の引き継ぎコストが変わります

この3つが書面にあれば、開発会社が替わっても連携は生き残ります。逆に、3つとも口頭のまま進んだ案件は、担当者が異動した時点で誰も全体を説明できなくなる。これが失敗のもとです。

当社の担い方——日本人PMをフロントに置いたラボ型で、連携部分を継続して持つ

当社TALENTBASE VIETNAMは、ホーチミンを拠点にベトナムのIT人財で開発チームを組む会社です。2,000名以上の人財データベースから直接アサインするため、協力会社や紹介を経由する仲介マージンがかかりません。体制は日本人PM/ブリッジSEをフロントに置くパターンAを推奨しており、1名から、最短2週間で開始できます。増員は約1週間、縮小や交代は1か月単位での対応です。契約と支払いは日本国内法人・日本法準拠で、海外送金は不要。日本との時差は2時間で、午前中に出した質問への回答がその日のうちに返ります。

API連携を含む案件で当社が実際に担ってきたのは、決済サービスと連携するアプリ(二要素認証、ウォレット、PDF出力を含む構成)を新規開発から週次保守まで持った案件や、外部のLLMを呼び出して24時間動くチャットボット、求人プラットフォーム、ヘッドレスCMSを使ったWebサイトなどです。介護記録SaaSのCareViewerでは、日本語が話せるブリッジSE1名とフルスタックエンジニア2名の体制で、週次に優先順位を判断しながら継続開発を行っています。

なぜラボ型かというと、外部APIの告知を読み、影響を調べ、必要なら直す作業は、一度で終わらないからです。スポットの請負契約では、この継続的な作業の置き場所がありません。品質面では、日本人PMによる設計レビュー、Gitのプルリクエストによるコードレビューの標準化、リリース前のダブルチェックを工程として組み込んでいます。クラウド基盤はAWS認定11冠の体制で担当します。費用は公開している単価で、実務3年目安1,500USD(約22.5万円)、5年2,000USD、10年目安とブリッジSEが3,000USD(1USD=150円換算目安)。最小構成は日本人PMフロント+2〜3人月で月額約80万円からです。

率直に言えば、向かない案件もあります。連携が1本だけで今後増える予定がなく、作ったら数年触らないと決まっているなら、月額の専属チームは過剰です。国内のスポット契約のほうが合います。逆に、連携先が複数あり、相手の仕様変更に追従し続ける必要があり、社内に専任の技術者がいない——この3つが当てはまるなら、継続して同じチームが持つ形に分があります。なお、ベトナムの祝日は2026年で年12日(労働法112条の法定は11日で、2026年からベトナム文化の日が加わります)、旧正月のテトは2026年2月14日から22日までで、この期間の対応方針は契約時に取り決めます。

【FAQ】APIに関するよくある質問

最後に、本文で扱いきれなかった周辺の疑問を5つ回収します。いずれも実際に発注の現場で聞かれることが多いもので、短く答えます。詳しい背景は本文の該当する章に戻ってご確認ください。

Q1. APIを一言で説明すると何ですか

ソフトウェアの機能やデータを、外から決まった手順で呼び出せるようにした窓口です。MDNは「提供する側と使う側のあいだの契約(インターフェース)」と表現しています。窓口である以上、様式も受付時間も本人確認も、開いている側が決めます。

Q2. API連携の費用はどう決まりますか

主に4つで動きます。①連携する処理の本数、②1回で扱える件数と呼び出し回数の上限(初回移行の時間に直結します)、③失敗時の再送や重複排除といった例外処理の作り込み、④試験環境があるかどうか。相場を一言で言えないのは、同じ「1本の連携」でも、相手の仕様によって工数が数倍変わるからです。

Q3. APIキーは社内の誰が持つべきですか

自社名義で発行し、自社側で保管するのが原則です。開発会社には作業に必要な範囲で貸し出し、担当者の交代や契約終了のタイミングで差し替えます。開発会社の名義で発行したまま進めると、会社を替えるときに連携ごと作り直しになることがあります。

Q4. 連携先がAPIを廃止したら、自社のシステムはどうなりますか

告知から停止までに移行期間が設けられるのが通例です。HTTPには非推奨を伝えるDeprecation、実際に応答しなくなる日を伝えるSunsetという仕組みが標準化されています。ただし、これは相手がそう運用した場合の話で、告知を読む担当が社内にいなければ意味を持ちません。読む人を決めておくこと、そして代替手段を1つ調べておくことが備えになります。

Q5. 自社のAPIを公開する前に決めることは何ですか

誰に開けるか(社内・パートナー・公開)、認証の方式、呼び出しの上限、バージョンの方針、問い合わせ窓口の5つ。公開するとは、その形を当面変えないと約束することでもあります。まずは社内APIやパートナーAPIから始め、需要を見て範囲を広げるという段階的な進め方。

まとめ: APIは機能を外から呼ぶための窓口——様式・受付時間・本人確認は、相手が決める

APIとは、あるソフトウェアが持つ機能やデータを、外から決まった手順で呼び出せるようにした窓口です。MDNはこれを「提供する側と使う側のあいだの契約(インターフェース)」と説明しています。1回の呼び出しで行き来するのは、リクエスト側が4つ(URL・メソッド・ヘッダー・パラメータ)、レスポンス側が2つ(ステータスコードと本体)。返るコードが4xxなら自社側の修正、5xxなら相手側の障害で、直す当事者が変わります。REST・GraphQL・SOAPという作法の違いはありますが、RESTは2000年の博士論文で定義された設計様式であって規格ではなく、そもそも多くの案件で作法は相手が決めています。発注者が時間を使うべきは、作法の比較ではありません。

押さえるべきは、つながった後です。認証(APIキーとOAuth 2.0)、呼び出し回数の上限(超えると429が返り、Retry-Afterで次の時刻が伝えられることがあります)、そして仕様変更。廃止を事前に伝えるDeprecationヘッダはRFC 9745として2025年3月に標準化され、応答しなくなる日を示すSunsetと併用できます。相手の都合で壊れることは、例外ではなく最初から織り込まれた前提です。問題が起きるのは、告知が出ていたのに読む担当が社内にいなかったときです。連携先にAPIがない場合の代替も、提供元への依頼、ファイル連携、自動化ツール、画面操作の自動化という順に壊れやすさが増していきます。

だからこそ、API連携を含む開発を外部チームに任せるときに発注側が握るのは、この3つです。連携先の仕様(仕様書の所在、試験環境の有無、アカウントは自社名義か)、障害時の扱い(一次対応は誰が何分以内に行い、相手側の障害を保守の範囲に含むか)、そして仕様書の納品(API仕様書を納品物一覧に1行書く)。技術ではなく取り決めの話なので、非エンジニアでも判断できます。継続的な改修を誰が持つかという視点はシステム改修・開発保守の外注に、専属チームを月額で持つ契約形態そのものはラボ型開発とはにまとめてあります。当社はホーチミンを拠点に、日本人PMをフロントに置いたラボ型で、外部APIの告知を読み、影響を調べ、必要なら直すという継続的な作業を同じチームが担う形をとっています。1名から、最短2週間で開始でき、最小構成は日本人PMフロント+2〜3人月で月額約80万円から。鍵とアカウントの名義はお客様側に残す形を標準にしています。ただし、連携が1本だけで今後増える予定がなく、作ったら数年触らないと決まっているなら、月額の専属チームは過剰です。現在の体制と要件をお聞かせいただければ、その判断を含めて概算見積もりでお答えします。合わない案件にはその旨も率直にお伝えします。