REST API設計 | ぽち先生と学ぶ IT基礎ノート

要点

REST（Representational State Transfer）は、Web上のAPIをどう設計するかについての考え方の1つです。中心となるのは「操作したい対象（リソース）をURLで表し、その対象に対して何をするかをHTTPメソッドで表す」という発想です。

例えば「ユーザー一覧を取得する」というAPIは、「ユーザーという対象（リソース）」に対して「取得するという操作」を組み合わせて表現します。

REST APIのURLは、動詞（〜する）ではなく、名詞（対象そのもの）で設計するのが基本です。「何をするか」はURLではなくHTTPメソッド側で表すためです。

https://api.example.comAPIサーバー

/usersリソース（複数形の名詞）

/123個別のID

/getUser のような動詞入りのURLではなく、/users/123 のように「対象＋ID」で表すのがリソース指向の考え方です。

ぽち先生のヒント図書館の本棚の背表紙のようなものです。棚には「取ってください」とは書かれておらず、「小説コーナーの123番」のように対象そのものが示されています。何をするか（借りる・返す）は、棚のラベルではなく利用者の行動（操作）で決まります。

同じURL（リソース）に対して、HTTPメソッドを使い分けることで、異なる操作を表現します。

GET /users/123取得する

POST /users新しく作成する

PUT /users/123丸ごと更新する

DELETE /users/123削除する

URLは「対象」を固定したまま、メソッドだけを変えることで、CRUD（作成・取得・更新・削除）という基本操作をシンプルに表現できます。

操作の結果は、レスポンスのステータスコードで伝えます。REST API設計では、操作の種類に応じて適切なステータスコードを返すことが重視されます。

2xx系成功。例：作成成功なら201、取得成功なら200。

4xx系リクエスト側の問題。例：存在しないIDなら404。

5xx系サーバー側の問題。例：処理中にエラーが起きたら500。

ステータスコード自体の詳しい意味は、Web技術基礎のHTTPに関するトピックでも解説しています。ここでは「操作の結果を、コードの種類で分かりやすく伝える」という設計上の役割に注目してください。

これらのルールを守ることで、初めてそのAPIを触る人でも「このURLとメソッドで何が起きるか」を予測しやすくなります。

バージョニングを考えずに設計する仕様変更のたびに互換性が壊れると、既存の利用者に影響が出る。URLに/v1/を含めるなど、バージョンを意識した設計が重要。

エラーレスポンスの形式がバラバラエンドポイントごとにエラーの返し方が違うと、呼び出す側の実装が複雑になる。エラーコードやメッセージの形式を統一しておく。

認証・認可の設計を最初に決めるAPIキーやOAuthなど、誰がどこまで操作できるかを設計の初期段階で決めておくと、後から作り直すコストを避けられる。

REST API設計とは、URLで「何を」、HTTPメソッドで「何をするか」を表す設計スタイルです。リソース指向のURLとメソッドの使い分けを意識することで、意味の分かりやすいAPIを作れます。