本文へスキップ
BecomeCoder
ブログ一覧コース一覧

Web APIとは？REST APIを初心者向けに図なしで噛み砕く

#WebAPI#REST#API#HTTP#JSON#初心者#独学

結論：Web API とは「プログラム同士が HTTP を通じてやり取りするための“注文窓口”」で、REST はその窓口の並べ方・呼び方を整理した“お作法（ルール）”です。 難しい言葉が多く見えますが、正体は「どのURLに・どの動詞で・どんなデータを渡し・どんな返事が返るか」の4つだけ。読むより、実際にリクエストを投げて返事を受け取ってみるのが一番はやいです。

Web APIとは何か（注文窓口のたとえ）

API は Application Programming Interface の略で、直訳すると「アプリケーション同士をつなぐ窓口」です。そのうち Web API は、その窓口をインターネット越し（HTTP）に置いたものを指します。

レストランを想像してください。あなた（＝あなたのプログラム）は厨房（＝サーバーの中身）に直接入れません。代わりに「メニュー」を見て、「店員」に注文を伝え、料理を受け取ります。このとき、

という対応になります。厨房の作り方（データベースの構造やプログラムの中身）を知らなくても、決められた注文の仕方さえ守れば料理が受け取れる。これが Web API の便利さです。天気アプリが気象データを表示できるのも、地図アプリが経路を出せるのも、裏で誰かの Web API に注文を出しているからです。

用語としての定義だけを確認したいときは、用語集の Web API と REST API も参照してください。この記事では「仕組みとつまずき」に絞って説明します。

リクエストとレスポンス ― やり取りの1往復

Web API のやり取りは、必ず「リクエスト（注文）」と「レスポンス（返事）」の1往復でできています。

この1往復を実際に自分の手で組み立てて動かせるのが、Djangoコースです。まず読み物の WebアプリとDjango ― リクエストからレスポンスまで で全体像をつかんだあと、はじめてのビュー ― Hello, Django から先はブラウザ上でそのまま実行できます。「リクエストが来たら、こう返す」という関数を書いて、返事が変わる様子をその場で確認できます（無料・環境構築なし・登録不要）。

エンドポイントとは ― 「どこに注文するか」

エンドポイントとは、機能ごとに割り当てられた注文先の住所（URL）です。メニューの各項目に対応します。

GET  /users        ← 利用者の一覧をください
GET  /users/42     ← 42番の利用者の情報をください
POST /users        ← 新しい利用者を登録してください

同じ /users でも「一覧」と「新規登録」で意味が変わるのは、次に説明する**メソッド（動詞）**が違うからです。URL が「どこに（名詞）」を表し、メソッドが「何を（動詞）」を表す、と覚えると整理しやすくなります。

URL をどう設計し、どの関数につなぐかは URLとビューを結ぶ ― urlpatterns と path でブラウザ上で動かしながら学べます。

HTTPメソッド ― GET / POST / PUT / DELETE

リクエストの先頭には必ず「何をしたいか」を表す動詞が付きます。これが HTTPメソッドです。初心者はまずこの4つを押さえれば十分です。

この4つは、データ操作の基本である「作る・読む・更新する・消す」（CRUD）にそのまま対応しています。GET と POST の使い分けは特に重要で、GETとPOST ― HTTPメソッドで分岐する で「同じURLでもメソッドによって処理を分ける」という実際のコードをブラウザで動かせます。リクエストの中身（送られてきたデータ）をどう取り出すかは リクエストの中身 ― HttpRequest と request.GET が具体的です。

JSON ― やり取りするデータの形

Web API でデータをやり取りするとき、いちばんよく使われる形式が JSON（ジェイソン）です。人間にも読めて、プログラムでも扱いやすい「キーと値」の書き方です。

{
  "id": 42,
  "name": "たろう",
  "tags": ["初心者", "Web"]
}

なぜ JSON かというと、どの言語からでも読み書きできる“共通語”だからです。サーバーが Python でも、受け取る側が JavaScript でも、JSON という文字列を経由すれば意味が通じます。JSON そのものを手を動かして理解するなら、JavaScriptコースの JSON ― データを文字列でやり取りする が最短です。ここも含めて JavaScriptコースは全28レッスンすべてブラウザで実行できます。

そして「実際に Web API に注文を出してJSONの返事を受け取る」体験ができるのが fetch ― サーバーからデータを取ってくる です。fetch でリクエストを送り、返ってきた JSON を取り出すまでを、模擬サーバー相手にブラウザ内でそのまま動かせます。通信は結果がすぐには返らないため非同期処理になります。この「待つ」仕組みでつまずいたら 非同期処理がわからない人向け｜Promiseとasync/await を合わせて読んでください。

ステータスコード ― 返事に付く「結果の合図」

レスポンスには、うまくいったか失敗したかを表す3桁の数字（ステータスコード）が必ず付いています。番号の百の位でおおまかな意味が決まります。

「404」を見たことがある人は多いはずです。あれは「注文先の住所が存在しない」という合図です。ステータスコードとリダイレクトの返し方は ステータスコードとリダイレクト でブラウザ上で確認できます。

REST APIとは ― 窓口を整理する“お作法”

ここまでの「URLは名詞・メソッドは動詞・JSONでやり取り・ステータスコードで結果を返す」という組み立て方を、きちんとルール化したものが REST（Representational State Transfer）です。REST に沿って作られた Web API を REST API と呼びます。

REST の考え方のうち、初心者が押さえるべきなのは次の点です。

つまり REST は新しい技術ではなく、「HTTP という既存の仕組みを、素直に・一貫したルールで使おう」という取り決めです。だから REST を理解する近道は、HTTP そのものに慣れること。HTTP の用語も合わせて確認しておくと、REST の各ルールが「なぜそうなっているか」まで腑に落ちます。

つまずきやすいところ

Web API の学習でよくある詰まりどころを挙げます。

次に読む

← ブログ一覧に戻る