APIとは ― Web APIの仕組みとマッシュアップ

スマートフォンの天気アプリは、天気を自分で観測していません。天気情報を配信する会社のプログラムに、決められた形で地名を送り、その日の天気を受け取っています。このやり取りの決まりが、API（Application Programming Interface）です。

APIとは、プログラムが別のプログラムの機能を使うために、呼び出し方を決めた窓口です。決められた書き方で頼めば、相手の中身を知らなくても、決められた結果が返ってきます。NISTの用語集の定義でも、APIは、プログラムから決まった書き方で呼び出すと、決まった機能を使える窓口です。

アプリがファイルを開くとき、アプリはディスクを直接操作しません。OSが用意した関数を、決められた引数で呼び出します。この関数の集まりも、OSのAPIです。

同じ約束を、ネットワークの先にある別のサービスとの間で決めたものがWeb APIです。Web APIでは、関数を呼ぶ代わりにHTTPのリクエストを送り、結果をレスポンスで受け取ります。呼び出し方を決めておき、中身を隠す考え方は、どちらも同じです。

Web APIを使うアプリは、提供元が決めたURLにHTTPのリクエストを送ります。リクエストには、何をしたいかを表すメソッドと、対象を指すURLが入ります。提供元のサーバは処理の結果をレスポンスで返し、アプリはその中身を自分の画面に使います。

図の天気アプリは、地図サービスと天気サービスに1回ずつリクエストを送っています。アプリが使うのは、それぞれのサービスの窓口であるAPIだけです。サービスの中で地図をどう描くか、天気をどう予報するかは、アプリから見えません。

レスポンスの先頭には、結果を3けたの数で表すステータスコードが入ります。RFC 9110では、200は成功、401は有効な認証の情報が無いこと、404は対象が見つからないことを表します。データを読むときのGET、作るときのPOSTなど、操作とメソッドの対応は、ネットワーク自動化の記事のREST APIの節にまとめています。

ここまでは、アプリの側からリクエストを送る形です。逆に、出来事が起きたときに相手のサービスからリクエストを送ってもらう仕組みがWebhookです。

Web APIのレスポンスの本文には、JSONがよく使われます。JSONは、構造を持つデータを文字だけで書き表す形式です。名前と値の組を集めたものはオブジェクトと呼び、波かっこで囲んで書きます。JSONはRFC 8259が定めていて、本文がJSONであることは、Content-Typeのapplication/jsonで示します。

{
  "city": "tokyo",
  "weather": "晴れ",
  "temp_max": 18,
  "temp_min": 9
}

左の"weather"が名前で、右の"晴れ"が値です。値には、文字列・数値・真偽値・nullのほか、配列や別のオブジェクトも入れられます。アプリは名前を手がかりに値を取り出すので、提供元が名前を変えると、アプリ側も直す必要があります。配列や入れ子を含むJSONの例は、ネットワーク自動化の記事のJSONの節にあります。

次の図は、天気サービスのWeb APIに送るリクエストと、返ってくるレスポンスを並べたものです。同じURLでも、APIキーの有無や指す対象によって、ステータスコードと本文が変わります。

GET /v1/cities/tokyo/forecast HTTP/1.1
Host: weather.example.com
Authorization: Bearer EXAMPLE-KEY-1234
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "city": "tokyo",
  "date": "2026-11-01",
  "weather": "晴れ",
  "temp_max": 18,
  "temp_min": 9
}

GET /v1/cities/tokyo/forecast HTTP/1.1
Host: weather.example.com
Accept: application/json

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="weather"
Content-Type: application/json

{
  "error": "missing_api_key",
  "message": "APIキーがありません"
}

GET /v1/cities/atlantis/forecast HTTP/1.1
Host: weather.example.com
Authorization: Bearer EXAMPLE-KEY-1234
Accept: application/json

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "not_found",
  "message": "その地点は見つかりません"
}

アプリは、まずステータスコードを見て、成功か失敗かを分けます。失敗のときも本文にJSONで理由が入ることが多く、アプリはそれを使って利用者に伝える文を決めます。番号ごとの意味と調べる場所は、HTTPステータスコードの記事で確かめられます。

公開されたWeb APIの多くは、使う前に利用の登録を求めます。登録すると、提供元から英数字の長い文字列が配られます。この文字列をAPIキーと呼びます。アプリは、リクエストのたびにこのキーを付けて送ります。

提供元は、キーを見て、どのアプリからの要求かを見分けます。キーごとに、リクエストの速さの上限や、決めた期間の中で使える回数の上限も決められます。Amazon API Gatewayの文書は、この上限をスロットリングとクォータとして説明しています。

ただし、APIキーは、利用者が誰で何をしてよいかを細かく決める仕組みには向きません。Amazon API Gatewayの文書も、APIへのアクセスを制御する認証や認可にキーを使わないよう勧めています。利用者に代わってデータを読む権限を、範囲と期限を決めて渡すときは、OAuthのアクセストークンを使います。

APIキーをコードやURLに書かない

APIキーは、パスワードと同じ秘密の情報です。ソースコードに書いたまま公開のリポジトリに置くと、誰でもそのキーで提供元のAPIを呼べます。料金がキーの持ち主に請求される場合は、他人の利用分まで払うことになります。

• キーは環境変数や秘密の情報を保管するサービスに置き、コードには書かない
• キーをURLのクエリに入れない。URLは閲覧の履歴やサーバのログに残る
• 漏れたと分かったら、そのキーを無効にして新しいキーを作る

Webの安全性に取り組む団体OWASPは、APIキーを管理すべき秘密の情報に含めています。そして、コードをリポジトリへ登録する前に、秘密の情報を見つける仕組みを置くよう勧めています。漏れたキーは、すぐに無効にするよう求めています。RFC 6750も、アクセストークンについて、URLに入れないよう同じ注意をしています。

マッシュアップとは、複数の提供元によるAPIを組み合わせて、新しいサービスを作る手法です。前の図の天気アプリは、地図の会社と天気の会社のAPIを組み合わせて、1つの画面にしています。自分で作るのは組み合わせ方だけで、地図や天気の仕組みは提供元のものを使います。

組み合わせ方には、結果を並べるだけの形と、あるAPIの結果を別のAPIに渡す形があります。たとえば、条件に合う店の一覧を1つ目のAPIで受け取り、その店ごとの混み具合を2つ目のAPIに問い合わせる形です。後者をロジックマッシュアップと呼びます。

生産性と品質面の特徴

• 生産性：地図や天気のような大きな機能を自分で作らずに済み、短い期間でサービスを作れる
• 品質面：提供元のAPIが止まったり遅くなったりすると、自分のサービスも同じように止まる
• 品質面：提供元が仕様を変えたり提供をやめたりすると、自分のサービスを直す必要がある

提供元の障害に引きずられないよう、レスポンスが来ないときに待つ時間の上限を決めておきます。片方のAPIが失敗しても、もう片方の結果だけで画面を出せるように作ると、全体が止まりにくくなります。

企業が自社のサービスをAPIで公開すると、他社がそれを組み込んだサービスを作れます。公開されたAPIで企業どうしのサービスがつながり、新しいサービスを生みながら事業を広げていく仕組みを、APIエコノミーと呼びます。

野村総合研究所の用語解説では、APIエコノミーを「API公開によって自社だけでなく、他社のサービスも活用して広がっていく商圏」としています。同じ用語解説は、銀行がAPIを公開し、家計簿のサービスと連携した例を挙げています。

公開する側から見ると、他社のサービスを経由して、自社のサービスが使われる場面が広がります。APIを使う側は、マッシュアップで新しいサービスを早く作れます。公開したAPIの仕様を変えると、つながった他社のサービスにも影響が及びます。

APIを公開する側では、多くのサービスのAPIを1つの入口にまとめることがあります。この入口をAPIゲートウェイと呼びます。APIゲートウェイは、リクエストを受けて正しいサービスへ振り分け、APIキーなどの確認と回数の上限の管理を引き受けます。

クラウドの事業者も、これをサービスとして用意しています。例として、AWSのAmazon API Gateway、MicrosoftのAzure API Managementがあります。マイクロサービスで分けたサービスの前に置く使い方は、マイクロサービスの記事で説明しています。リクエストが来たときだけコードを動かすサーバーレスと組み合わせて、APIを作ることもあります。

• NIST CSRC Glossary「application programming interface (API)」
• RFC 9110「HTTP Semantics」（9.3.1、11.6.2、15.3.1、15.5.2、15.5.5）
• RFC 8259「The JavaScript Object Notation (JSON) Data Interchange Format」（1章・11章）
• RFC 6750「The OAuth 2.0 Authorization Framework: Bearer Token Usage」（2.1、2.3、5.3）
• Amazon API Gateway Developer Guide「What is Amazon API Gateway?」
• Amazon API Gateway Developer Guide「Usage plans and API keys for REST APIs in API Gateway」
• Microsoft Learn「Azure API Management - Overview and Key Concepts」
• OWASP「Secrets Management Cheat Sheet」（1章、8.1、8.2、9.2）
• 野村総合研究所「用語解説 APIエコノミー」