APIとは？要求と応答、利用条件、失敗時の扱いを学ぶ入門ガイド

30秒で要点

• APIは、ソフトウェア同士が機能やデータをやり取りするための取り決めです。Webサイトをまたぐ連携だけでなく、ブラウザなどが提供するAPIもあります。
• Web APIでは、どこへ何を送るか、誰が使えるか、何が返るかを仕様で確認します。APIキーが必要かどうかも、提供元や機能によって異なります。
• 接続できれば完成ではありません。利用料金、権限、データの扱い、エラー、変更・停止時の対応を確認してから業務に組み込みます。

「決済APIを使えばつなげられます」「この情報はAPIで取得できます」と説明されても、何を準備すればよいか分からない。この記事は、開発者との会話やサービス選定のためにAPIの仕組みを知りたい人に向けた入門です。

まず窓口のたとえで要求と応答を理解し、その後にREST・GraphQL・SOAP、利用の流れ、安全と失敗時の扱いを説明します。後半の小さな例は通信を行わず、架空の天気データを手元で読むものです。実APIへ登録したり、認証情報を用意したりする必要はありません。

APIは、ソフトウェアが使うための窓口と取り決め

APIはApplication Programming Interfaceの略です。利用する側が内部の処理をすべて作り直さなくても、決められた方法で機能やデータを利用できるようにします。MDNのAPIの説明

レストランでは、客がメニューから料理を選び、注文を伝え、結果を受け取ります。厨房の配置や調理の細部を知らなくても注文できるのは、注文方法があるからです。APIにも、頼めること、必要な条件、返す形式という取り決めがあります。

ただし、APIは人が事情を察してくれる窓口ではありません。必須項目がない、許可されていない操作をする、入力の形式が違う、といった要求は失敗することがあります。何を送ってよいかを仕様で確認する必要があります。

また、APIは必ずしもインターネット上の別会社のサービスとは限りません。ブラウザの位置情報やアニメーションなどの機能にもAPIがあります。本記事では、業務で話題になりやすい、ネットワーク越しに使うWeb APIを中心に扱います。

日常のサービスと、APIでできること

表が収まらない場合は、横にスクロールできます

既存の機能を使うことで、一から作る範囲を減らせる場合があります。ただし、接続先の仕様に合わせる作業や、障害時の対応は残ります。「APIがある」ことだけで、短納期・低費用・高品質が決まるわけではありません。

連携が増えると、同じデータを二重入力する負担を減らせることがあります。一方、どちらを正しいデータとするか、削除や更新をどの順で伝えるかを決めなければ、不一致も起きます。自動化する前に、人が現在どこで判断しているかを確認すると、任せられる範囲が分かります。

要求と応答で使う言葉を整理する

Web APIでは、利用する側がリクエスト（要求）を送り、提供する側がレスポンス（応答）を返します。電話で問い合わせる代わりに、ソフトウェアが形式の決まったメッセージを交換するイメージです。

表が収まらない場合は、横にスクロールできます

宛先が分かっても、どんな条件を送れるか、どの権限が必要かは別に確認します。ブラウザで画面を開くときのログインと、プログラムがAPIを使う認証も、同じ方式とは限りません。

JSONを読む小さな練習

次は架空の天気データです。weather.json という名前で保存できます。晴れ、25度、湿度60%という値は説明用であり、実際の予報ではありません。

{
  "city": "tokyo",
  "weather": "晴れ",
  "temperatureC": 25,
  "humidityPercent": 60
}

temperatureC の C はこの教材で摂氏を表すために付けた名前です。実APIでも同じ名前で返るわけではありません。気温の単位や、取得時刻・予報対象時刻の意味は、そのAPIの仕様で確認します。

JSONにはオブジェクト、配列、文字列、数値、真偽値、null などがあります。JSONを読めることと、そのデータが正しいことは別です。たとえば湿度が文字列で返っていないか、必要な項目が欠けていないかも確認します。JSONの仕様 RFC 8259

次の read-weather.mjs を同じフォルダーへ保存し、Node.jsで node read-weather.mjs と実行すると、ファイルを読んで表示できます。追加パッケージ、APIキー、通信は不要です。

import fs from 'node:fs';
import assert from 'node:assert/strict';

function formatWeather(data) {
  if (!data || typeof data !== 'object' || Array.isArray(data) ||
      typeof data.city !== 'string' || !data.city.trim() ||
      typeof data.weather !== 'string' || !data.weather.trim() ||
      !Number.isFinite(data.temperatureC) ||
      !Number.isFinite(data.humidityPercent) ||
      data.humidityPercent < 0 || data.humidityPercent > 100) {
    throw new TypeError('Invalid weather data');
  }
  return `${data.city}: ${data.weather}、${data.temperatureC}℃、湿度${data.humidityPercent}%`;
}

const data = JSON.parse(fs.readFileSync(new URL('./weather.json', import.meta.url), 'utf8'));
assert.equal(formatWeather(data), 'tokyo: 晴れ、25℃、湿度60%');
assert.throws(() => formatWeather({ ...data, humidityPercent: 101 }), TypeError);
assert.throws(() => formatWeather({ ...data, temperatureC: '25' }), TypeError);
console.log(formatWeather(data));

この確認は、項目と型の一部に限定しています。気温の物理的な妥当性、地域の識別、予報の鮮度まで検証しているわけではありません。実APIへの接続では、通信、認証、応答の状態、タイムアウトなどの処理が別途必要です。

REST・GraphQL・SOAPの違い

これらは、どれが常に優れているかを決める順位ではありません。また、三つとも同じ種類の製品名ではありません。既存システムや提供元の仕様を理解するための分類として使います。

表が収まらない場合は、横にスクロールできます

RESTは「URLへ送るとJSONが返るもの」の別名ではありません。Fieldingの原典では、統一インターフェースなど複数の制約が説明されています。入門では、リソースと操作を一定のルールで表す考え方から理解するとよいでしょう。RESTの原典

GraphQLでは、スキーマで定義されたフィールドを指定して取得します。必要な形を要求できる一方、サーバー側の処理や権限、複雑な問い合わせの負荷は残ります。「必要なデータだけだから必ず高速」とは限りません。GraphQLの公式入門

SOAPはXMLを使うメッセージの枠組みで、さまざまな下位の通信方式上で利用できます。採用方式の名前だけで安全性や信頼性を判定せず、認証、暗号化、権限、実装と運用を確認します。W3CのSOAP仕様

自社で新しく設計する場合は、利用者、操作の種類、既存の技術、変更への対応から選びます。既存サービスを利用する場合は、提供されている契約をまず読むことが出発点です。設計側の詳しい比較はAPI設計の実践ガイドで扱っています。

APIを使い始めるまでの流れ

APIの利用開始には、次のような順序があります。すべてのAPIでアカウントやキーが必要なわけではありません。公開データ、ユーザーごとの認証、サーバー専用の操作などで条件が変わります。

1. やりたいことを決める：必要なデータ、読み取りか書き込みか、どの頻度で使うかを整理する。
2. 公式仕様と利用条件を読む：認証、料金、上限、保存・再利用の条件、変更情報を確認する。
3. 必要なら利用申請や認証を準備する：用途に合う権限と環境を選ぶ。
4. 小さな要求で応答を確認する：許可されたテスト環境や合成データを使い、通常時と失敗時を見る。
5. 業務へ組み込む条件を決める：監視、問い合わせ先、費用上限、更新、停止時の代替を用意する。

仕様を読むときは、正常な応答例だけでなく、必須項目、エラー、ページ分割、呼出し回数の制限も探します。取得対象が多ければ、一回ですべて返るとは限りません。仕様変更の通知を誰が受け、どの期限で対応するかも運用の一部です。

ノーコードの連携サービスに対応していれば、プログラムを自分で書かずに使える場合もあります。ただし、認証情報、項目の対応、失敗時の処理や費用が不要になるわけではありません。対応していない機能や複雑な例外は、開発が必要になります。

APIキーは、用途と置き場所を確認する

APIキーを「何でもできるパスワード」と理解すると、扱いを誤ることがあります。識別や認証に使うものでも、公開してよい範囲、権限、有効期限、環境は提供元によって違います。

たとえばStripeは、公開可能キー、秘密キー、権限を制限したキーを区別しています。公開可能キーがあることを根拠に、秘密キーもWebページへ書いてよいとは判断できません。テスト用と本番用の環境も分かれています。StripeのAPIキーの説明

秘密の認証情報は、公開リポジトリ、ブラウザへ配るJavaScript、画面写真、問い合わせ文、ログへ残さないようにします。誰が発行・更新・無効化できるかを決め、必要な操作だけに権限を絞ります。人の退職や委託終了時に、その人しか管理できない状態を残さないことも必要です。

HTTPSなどの暗号化通信は、途中での盗み見や改変への対策の一部です。それだけで、間違った相手への送信、権限の広すぎるキー、誤った入力、保存先の問題まで解決するわけではありません。

失敗したときは、同じ要求を送る前に状態を見る

APIの呼出しは、入力、権限、利用上限、通信、提供側の事情などで失敗します。エラーメッセージを利用者へそのまま表示して、秘密情報や内部事情を漏らさないことにも注意します。

表が収まらない場合は、横にスクロールできます

特に、返事が届かないことと、処理されていないことは同じではありません。決済が完了した後に応答だけ失われると、再送で二重処理になる可能性があります。提供元が用意する重複防止の方法や結果照会を確認します。

HTTP仕様は、冪等性と再試行の条件を区別しています。冪等とは、同じ要求を繰り返したときの意図された効果が一回と同じになる性質です。すべてのAPIの書込みがその性質を持つわけではなく、非冪等な要求を自動再試行するには、安全に判断できる条件が必要です。HTTPの仕様 RFC 9110

失敗時に「後で再開できる」「担当者へ確認を回す」「一部の表示を古いデータと明示して継続する」など、業務に合う代替を決めます。古い在庫や価格を無条件に使い続けることは避け、許される鮮度を定めてください。

費用と提供条件は、利用量を置いて確認する

無料で使えるAPIもありますが、常に無料、商用利用も自由、上限なしとは限りません。アカウントの契約、呼出し回数、データ量、利用する機能によって費用や制限が変わります。現在の料金は提供元で確認し、確認日を残します。

たとえば、画面表示のたびに1回呼ぶ設計で1日1,000回表示されるなら、単純計算では30日で30,000回です。これは架空の計算例で、料金の見積もりではありません。再試行、ページ分割、定期処理、複数の要求が必要な画面があれば回数は増えます。キャッシュできる場合でも、保存の可否と許される鮮度を確認します。

契約の比較には、月額や従量料金だけでなく、超過時の扱い、停止できるか、テスト環境、問い合わせ窓口、仕様変更と提供終了の通知、データの持ち出しや移行も含めます。担当者が変わっても継続できるよう、利用している機能と連絡先を記録します。

5分で確認する、導入前の問い

• 何を自動化し、どの判断を人に残すか説明できるか。
• 読むだけか、作成・更新・削除もするか区別できるか。
• 必要な情報をその提供元へ送ってよいか確認できるか。
• 料金・利用上限・権限・変更通知を誰が管理するか決まっているか。
• 応答がないときに、重複処理を避けて復旧できるか。

答えが分からない項目は、契約前や実装前に提供元・開発担当へ確認する内容になります。APIを理解する第一歩は、技術用語をすべて覚えることではなく、頼めること、渡すもの、返るもの、失敗時の責任を分けて話せることです。

Web開発の全体像は現代のWeb開発ガイド、設計や実装の条件はAPI設計の実践ガイドにつながります。