API とは何か — プログラム同士の受け渡しの約束・JSON

この記事は、API を扱います。

API は、プログラム同士がデータをやり取りするための約束事です。

呼び出しの 3 要素と、返ってくる JSON という文字の形式まで確かめます。

• 「API を呼ぶ」が、実際にはどこへ何を送ることなのか
• 呼び出しの 3 要素 — URL・メソッド・レスポンス
• 返ってくるJSONのキーと値の読み方
• 成功と失敗を表すステータスコードと、番号ごとの次の一手

「API を呼ぶ」は、決められた URL にリクエストを送り、レスポンスを受け取ること

天気のデータを持っているのは自分のプログラムではなく、外部サービスのサーバーです。

HTTP のリクエストとレスポンスで呼ぶ API をWeb APIといい、受け付ける URL の 1 つ 1 つがエンドポイント（endpoint）です。

外部サービスも、my-app のサーバーも、提供する側になれます。

そして 1 つの画面が呼ぶエンドポイントも、1 本とは限りません。

ページが出るまでに、リクエストとレスポンスの往復が 3 回起きています。

ブラウザが直接つながるのは、my-app のサーバーだけです。

同じサーバーが、ブラウザから見れば提供する側、天気 API から見れば呼ぶ側になります。

API を呼ぶとは、送って受け取ること

API を呼ぶとは、決められた URL にリクエストを送り、返ってきたレスポンスを受け取ることです。

その URL の 1 本 1 本がエンドポイントで、呼ぶ側はブラウザのことも自分のサーバーのこともあり、提供する側も外部サービスとは限りません。

呼び出しの 3 要素 — URL・メソッド・レスポンス

手順書や説明書に書かれているのは、3 つのことだけです。

どこに送るか（URL）、何をしたいか（メソッド）、何が返るか（レスポンス）です。

1 つ目の URL は、? を境に前と後ろで役目が分かれます。

? より後ろがパラメータ（query parameter。欲しいデータの条件を 名前=値 の形で URL の末尾に付けたもの）で、クエリパラメータとも書きます。

2 つ目の要素がメソッド（HTTP method。リクエストで「何をしたいか」を示す、GET や POST のような決められた語）です。

行の先頭に書き、同じ URL に送っても動作が変わります。

GET は相手のデータを変えませんが、POST は送った時点で相手のデータが変わります。

手順書には、メソッドと URL を並べた形で書かれています。

# で始まる行は説明で、その下の 1 行が呼び方です。

# 天気を取得する。先頭がメソッド、後ろが URL（末尾がパラメータ）
GET https://api.example.com/weather?city=tokyo

# 予約を 1 件登録する。URL が同じでもメソッドが違えば別の動作
POST https://example.com/reservations

この呼び方と、返ってくるレスポンスの形をまとめたものがAPI ドキュメント（API reference）です。

手順に「API ドキュメントを見てください」とあれば、3 要素をそこで調べます。

送る前に自分で決めるのは 2 つ

送る前に自分で決めるのは、どこに送るかと、何をしたいかの 2 つだけです。

どこに送るかが URL で ? より前がエンドポイント、何をしたいかがメソッドで、3 つ目のレスポンスだけは自分では決められず、返ってきたものを読むことになります。

JSON は、キーと値の組でデータを書き表す文字の形式

手順の「返ってきた JSON」が、レスポンスの本体です。

JSON（JavaScript Object Notation。データをキーと値の組で書き表す、文字だけでできた形式）は、 Web API の本体に使われる代表的な形式です。

天気 API が返す JSON は、こういう形をしています。

{
  "city": "Tokyo",
  "temp": 23.5,
  "rain": false,
  "forecast": [
    { "day": "mon", "high": 25 },
    { "day": "tue", "high": 22 }
  ]
}

並んでいるのはキーと値（key / value。値に付けた名前がキーで、その名前が指す中身が値）の組です。

"temp": 23.5 なら temp がキー、23.5 が値で、キーと値は : で結び、組と組は , で区切ります。

{ } の中に組が並び、その値がまた [ ] や { } になっていることがあります。

4 つ目の値が配列（array。複数の値を [ ] の中に順番に並べたもの）で、1 件 1 件がまた { } で囲まれています。

{ } と [ ] は、何段でも入れ子にできます。

配列から 1 つ取り出すときは [0] のように番号で指し、番号は 1 からではなく 0 から数えます。

[ ] や { } でない値の書き方は 3 種類で、" " が付くかどうかで見分けます。

受け取ったままの本体は 1 本の長い文字列なので、キーを指定しても値は取り出せません。

入門書では JSON.parse のような 1 行でキーの読める形に変えてから、data.city のようにキーの名前で値を指します。

いちばん下の行だけは、キーの綴りをわざと 1 文字間違えてあります。

綴りを間違えてもエラーは出ないので、undefined になったらまず綴りを JSON と見比べます。

名前に JavaScript が入っていますが、どの言語からも読み書きできるので API のレスポンスに使われます。

JSON は名前と中身の組が並んでいるだけ

JSON は、名前とその中身の組を並べて書いただけの文字の並びです。

名前がキー、中身が値で、受け取ったままでは 1 本の長い文字列なので、キーで読める形に変えてから取り出します。

レスポンスは成功とは限らない — ステータスコードで処理が分かれる

天気 API は自分のプログラムの外で動くので、呼び出しは失敗することがあります。

そのためレスポンスは、本体だけで届くのではありません。

返ってくるもの 1 つを、分けて見てください。

先頭の 3 桁がステータスコード（status code。成功か失敗かとその種類を表す番号）です。

先に番号を見て、成功のときだけ本体からキーを読みます。

番号は 3 桁を丸暗記するものではなく、先頭の 1 桁で次の動きが決まります。

同じ天気 API でも、送った内容や提供側の状態で返る番号は変わります。

404 のほかに、提供する側で異常が起きたときは 500 が返ります。

404 は「ページが無い」だけの番号ではなく、API では、パラメータの条件に合うデータが無いときにも返ります。

手順どおり呼んで 404 が返ったら、綴りとパラメータを API ドキュメントと見比べます。

4 で始まる番号のうち 401 は、呼ぶ側が誰かを示すものが無い、または正しくないときの番号です。

それを示すためにリクエストへ付けるのが API キーです。

番号を見てから本体を読む

返ってきたレスポンスは、番号を見てから本体を読みます。

2 で始まるなら本体にほしいキーが入っていて、4 で始まるなら送った URL と条件を直し、5 で始まるなら少し待って呼び直します。