REST APIとは｜HTTPメソッド・エンドポイント・ステータスコードをやさしく解説

Webアプリやスマホアプリの裏側では、画面に表示するデータを取りに行ったり、入力した内容を送ったりする通信が絶えず行われています。その通信の窓口となる仕組みがAPIであり、なかでも現在もっとも広く使われている設計スタイルがREST APIです。本記事では、APIとは何か、RESTとはどんな考え方か、そしてHTTPメソッドやステータスコード、JSONによるやり取りまでを順を追って解説します。

APIとRESTとは何か

API（Application Programming Interface）とは、ソフトウェア同士がやり取りするための「窓口」や「約束ごと」です。たとえば天気アプリは、自分で気象データを持っているわけではなく、気象サービスのAPIに「この地域の天気を教えて」と問い合わせて結果を受け取っています。APIがあるおかげで、相手の内部構造を知らなくても、決められた手順でデータや機能を借りられるのです。

REST（REpresentational State Transfer）とは、そのAPIをWebの仕組み（HTTP）をそのまま素直に使って設計しようという考え方・スタイルです。RESTの考え方に沿って作られたAPIをREST APIと呼びます。RESTにはいくつかの原則がありますが、初心者がまず押さえるべきは次の2点です。

• リソース指向：操作の対象を「ユーザー」「記事」「注文」といったリソース（資源）として捉え、それぞれにURL（住所）を割り当てます。
• ステートレス：サーバーは前回のやり取りを覚えていない前提で、1回のリクエストに必要な情報をすべて含めて送ります。これによりサーバーを増やしやすく、スケールしやすくなります。

つまりREST APIは、「どのリソースに（URL）」「何をするか（HTTPメソッド）」を組み合わせて操作を表現する、シンプルで分かりやすい仕組みなのです。

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

REST APIでは、リソースに対して「何をしたいか」をHTTPメソッドで表します。代表的な4つは、データの基本操作であるCRUD（作成・参照・更新・削除）にほぼ対応しています。

GETはもっともよく使うメソッドで、データを読み取るだけで対象を変更しません。何度実行しても結果が変わらない（副作用がない）ため、ブラウザのアドレスバーに入力するのもGETです。POSTは新しいデータを送って作成する操作で、フォームの送信などに使われます。PUTは既存のリソースを丸ごと更新し、DELETEは削除します。なお、一部だけを更新するPATCHというメソッドもよく使われます。

ここで重要なのがべき等性という性質です。GET・PUT・DELETEは「同じリクエストを何度送っても最終的な状態が同じ」になるべき操作で、これをべき等といいます。一方POSTは送るたびに新しいリソースが増えるため、べき等ではありません。通信が途中で失敗したときに安全に再送できるかどうかに関わる、大切な考え方です。

エンドポイントとリソース設計

エンドポイントとは、リソースにアクセスするための具体的なURLのことです。RESTでは、エンドポイントを名詞（リソース名）の複数形で表し、操作はメソッドで区別するのが定石です。たとえばユーザーを扱うAPIなら、次のように設計します。

GET /users → ユーザー一覧を取得
GET /users/123 → ID 123のユーザーを取得
POST /users → ユーザーを新規作成
PUT /users/123 → ID 123のユーザーを更新
DELETE /users/123 → ID 123のユーザーを削除

ポイントは、URLに/getUserや/deleteUserのような動詞を入れないことです。「何をするか」はメソッドが表すので、URLは「どのリソースか」だけを素直に表現します。これにより、エンドポイントの数を抑えつつ、規則的で予測しやすいAPIになります。

リソースには階層関係を持たせることもできます。たとえば/users/123/ordersなら「ID 123のユーザーの注文一覧」を意味します。こうしたURLの構造を分解して確認したいときは、URLパーサーツールでパスやクエリ部分を分けて眺めると、設計の意図が把握しやすくなります。複雑なエンドポイントほど、URLパーサーツールで各要素を切り分けて確認すると理解が進みます。

ステータスコードの読み方

リクエストに対して、サーバーは結果をHTTPステータスコードという3桁の数字で返します。先頭の数字でおおまかな意味が分かるようになっており、ここを押さえるとAPIの応答を素早く読み解けます。

2xxは成功を表し、データ取得に成功すれば200、新規作成に成功すれば201が返るのが一般的です。4xxはリクエストを送った側に問題があることを示し、404は「リソースが見つからない」、401は「認証が必要・失敗」、400は「リクエストの形式がおかしい」を意味します。5xxはサーバー内部の不具合で、利用する側ではなく提供側の問題です。エラーが起きたときは、まずこの番号を見て「自分側の問題か、相手側の問題か」を切り分けるのが第一歩です。

リクエストとレスポンス：JSONとクエリパラメータ

REST APIのデータのやり取りには、現在ほとんどの場合JSON（JavaScript Object Notation）という軽量なデータ形式が使われます。人間にも読みやすく、プログラムでも扱いやすいのが特長です。たとえばユーザー作成のPOSTリクエストでは、次のようなJSONを本文（ボディ）に入れて送ります。

{
  "name": "山田太郎",
  "email": "taro@example.com"
}

サーバーは処理結果を、同じくJSONで返します。たとえば作成に成功すれば、付与されたIDを含むレスポンスが返ってきます。受け取ったJSONが入り組んでいて読みにくいときは、JSONフォーマッターツールに貼り付けてインデントを整えると、構造が一目で分かります。改行のない1行のJSONも、JSONフォーマッターツールで整形すれば階層がはっきり見えるようになります。

一方、GETでデータを取得する際の絞り込みや並び替えにはクエリパラメータを使います。URLの末尾に?を付け、キー=値を&でつなげて指定します。

GET /users?role=admin&sort=created&page=2

この例は「管理者ロールのユーザーを、作成日順で、2ページ目だけ取得する」という意味です。パラメータがいくつも連なって読みにくいときは、前述のURLパーサーツールでクエリ部分をキーと値に分解すると確認が楽になります。

認証の概要

誰でも自由にアクセスできるAPIもありますが、多くのAPIは利用者を確認する認証（Authentication）を必要とします。RESTはステートレスなので、原則として毎回のリクエストに認証情報を含めて送ります。代表的な方式は次のとおりです。

• APIキー：発行された文字列をヘッダーやクエリに付けて送る、もっとも手軽な方式。
• Bearerトークン（JWTなど）：ログイン後に受け取ったトークンをAuthorizationヘッダーに入れて送る方式。現在の主流です。
• OAuth 2.0：第三者サービスのデータに、パスワードを渡さず安全にアクセスを認可する仕組み。「Googleでログイン」などで使われます。

いずれの方式でも、認証情報は秘密の鍵に相当します。URLのクエリに直接書くと履歴やログに残りやすいため、通常はヘッダーに入れ、必ずHTTPS（暗号化通信）でやり取りします。認証が通らなければ、前述の401や403（権限なし）が返ります。

ここまで見てきたように、REST APIは「リソース（URL）」「操作（HTTPメソッド）」「結果（ステータスコード）」「データ（JSON）」という少数の部品の組み合わせで成り立っています。まずは身近なAPIのレスポンスをJSONフォーマッターツールで整形して眺め、エンドポイントをURLパーサーツールで分解してみると、仕組みが具体的につかめるはずです。手を動かして観察することが、API理解への近道です。

なお本記事は一般的な情報の提供を目的としたものです。APIの仕様や認証方式、推奨される設計は提供元やバージョンによって異なり、時間とともに変わることもあります。実際に利用する際は、対象APIの最新の公式ドキュメントを必ず確認したうえで判断してください。