API とは

API（エーピーアイ）は、ソフトウェアどうしがデータや操作をやりとりするために用意された、決まった窓口です。Application Programming Interface の略で、人が画面を見てボタンを押す代わりに、プログラムが決まった形で頼みごとを送り、決まった形で答えを受け取ります。

たとえば、教室の申し込みフォームに届いた内容を毎回手で名簿に写しているなら、両方のツールに API があれば、その作業をプログラムや自動化のツールに任せられます。しくみを知っておくと、ツールを選ぶときに「ほかのツールとつなげるか」を判断でき、つなぐときの注意点（鍵の扱いや回数の上限）もわかります。

API は何のためにあるのか

Web のサービスには、ふつう 2 つの入口があります。人が使う画面と、プログラムが使う API です。画面は人の見やすさのために作られ、見た目がよく変わります。API はプログラムが扱いやすいように形が決められ、文書にまとめられています。

たとえば、次のようなことができます。

• オンライン講座のサイトで、決済サービスの API を通して支払いを受け付ける
• 小さな会社の問い合わせフォームの内容を、顧客管理のツールへ自動で登録する
• 毎週手で集めていた数字を、表計算ソフトや自社の集計表へ取り込む

なお「API」という言葉はもっと広く、ソフトウェアの部品どうしの決まりごと全般を指すこともあります。この記事では、インターネットを通して HTTP（ブラウザーが Web のページを読み込むときと同じ通信の決まり）で呼び出す「Web API」について説明します。HTTP については MDN の「HTTP の概要」がくわしいです。

API はどう動くのか

API のやりとりは、役所や銀行の窓口に似ています。窓口ごとに受け付ける用件が決まっていて、決まった用紙に書き、本人であることを示して出すと、決まった形で返事が来ます。

窓口でのやりとり	API での呼び名
どの窓口に出すか	エンドポイント（URL）
照会・申し込み・変更・取り下げのどれか	HTTP メソッド
書き込んだ申込用紙	リクエスト（頼みごと）の本文
本人や代理人であることを示すもの	API キーなどの認証情報
窓口からの返事と受付の結果	レスポンス（答え）とステータスコード

やりとりの流れは次のとおりです。

1. プログラムが、エンドポイントに HTTP メソッドを付けてリクエストを送る
2. API が、API キーなどで誰からの頼みかを確かめる
3. 中身が決まりに合っているかを確かめてから処理する
4. 結果をレスポンスとして返す

ただし、API の窓口に人はいません。書き方が少しでも決まりと違うと、気を利かせて読み取ってはくれず、断られます。そのため API ごとに、エンドポイントや項目、エラーを細かく書いたリファレンス（使い方の文書）が用意されています。

エンドポイントとは

エンドポイントは、API の中で「どのデータに頼むか」を指す URL です。たとえば https://api.example.com/v1/courses が講座の一覧、https://api.example.com/v1/courses/42 が 42 番の講座、というように決めます。途中の v1 は版の番号で、形を大きく変えても古いつなぎが動き続けるようによく使われます。

HTTP メソッドとは

同じエンドポイントでも、HTTP メソッドで頼みの種類を分けます。よく使うのは次の 5 つです。

メソッド	意味	例
GET	読み取る	講座の一覧を取得する
POST	新しく作る・送る	申し込みを 1 件登録する
PUT	まるごと置き換える	講座の情報を全部書き換える
PATCH	一部だけ変える	定員だけを変える
DELETE	消す	取り消された申し込みを消す

GET は読み取るだけなので、HTTP の決まりでは、何度送ってもサービス側のデータは変わりません。一方、POST は送るたびに新しく作るのがふつうです。通信が途切れたからといって同じ POST をそのまま送り直すと、申し込みが 2 件できてしまうことがあります。メソッドの一覧は MDN の「HTTP リクエストメソッド」で確かめられます。

ステータスコードとは

レスポンスには、結果を表す 3 けたの数字（ステータスコード）が付きます。200 番台は成功、400 番台は頼み方の問題、500 番台はサービス側の問題を表します。

コード	意味
200 / 201	成功した・新しく作れた
400	中身が決まりに合っていない
401	誰からの頼みか確かめられない（キーがない・違う）
403	誰かはわかったが、その操作は許されていない
404	指したものが見つからない
429	リクエストが多すぎる
500	サービスの中で思わぬ問題が起きた

JSON とは何か

リクエストやレスポンスの中身には、JSON（ジェイソン）という書き方がよく使われます。JSON は、データを「名前と値の組」で書く文字の形式で、人にもプログラムにも読みやすいのが特徴です。

たとえば、申し込みを 1 件表すと {"name": "山田 花子", "course": "初級", "seats": 1} のようになります。name や course が名前（キー）、"山田 花子" や 1 が値です。値には、文字・数・真偽（true / false）・空（null）のほか、角かっこで囲んだ並びや、さらに入れ子にした組を入れられます。

JSON は特定のプログラミング言語に縛られないので、別々の言語で作られたツールどうしでもやりとりできます。どの名前にどんな値が入るかは、API のリファレンスで確かめます。

API キーはなぜ秘密にするのか

API キーは、API に「誰からの頼みか」を伝える長い文字列です。合鍵や、代理人に渡す委任状のようなものだと考えるとわかりやすいでしょう。多くの API では、リクエストの Authorization ヘッダー（本文とは別に付ける添え書き）に、Bearer という言葉と一緒に付けて送ります。

API キーを知っている人は、そのキーに許された範囲で、あなたの組織として API を使えます。データを読まれたり、書き換えられたり、回数の上限まで使われたりするので、パスワードと同じように扱います。

次のようにしておくと安心です。

• Web ページの JavaScript など、ブラウザーに届くコードに書かない（ページを見る人が読めてしまいます）
• 公開のリポジトリ、チャット、メール、画面の写真に載せない
• サーバーの環境変数や、ツールの秘密の設定欄など、決められた場所にしまう
• 読むだけの用途には、読み取りだけのキーを使う
• ツールごとにキーを分け、名前を付けておく（あとで 1 つだけ止められます）
• 使わなくなったキーや、漏れたかもしれないキーは失効させ、作り直す

キーが漏れたと気づいても、慌てなくて大丈夫です。失効させれば、そのキーはもう使えません。新しいキーをつなぎ直してから、利用の記録に心当たりのない呼び出しがないかを確かめます。

レート制限とは

レート制限は、一定の時間に受け付けるリクエストの数の上限です。「1 秒に 10 回まで」「1 日に 1,000 回まで」のように決められます。1 つのプログラムの誤りや使いすぎで、ほかの利用者まで使いにくくなるのを防ぐためのものです。

上限を超えると、ふつうはステータスコード 429（Too Many Requests）が返ります。Retry-After ヘッダーで「どれだけ待てばよいか」を教えてくれる API もありますが、付かないこともあります。くわしくは MDN の「429 Too Many Requests」を参照してください。

上限とうまく付き合うには、次の点を押さえます。

• 429 が返ったら、すぐに送り直さず、待つ時間を少しずつ延ばしながら送り直す
• たくさん登録するときは、まとめて送れる API があればそれを使う
• 同じデータを何度も取りに行かず、手元に保存して使い回す
• 結果がわからない書き込み（POST など）は、自動で送り直す前に、登録されたかどうかを確かめる

まとめ

• API は、ソフトウェアどうしが決まった形でやりとりする窓口です
• エンドポイントで「どこに」、HTTP メソッドで「何を」頼み、中身は JSON で送ります
• API キーはパスワードと同じく秘密にし、権限を絞ります
• 上限を超えたら間を空けて送り直し、書き込みの送り直しには気を付けます

出来事が起きたときに相手から知らせてもらうつなぎ方は、「Webhook とは」で説明しています。