REST API設計

REST APIを設計するにあたってパスやHTTPメソッドなど、考えるべき事柄に対する指針を例示します。

パス

RESTの定義に沿って、リソースを表すものとして使用します。

どのようなリソースであるかを分かりやすくするため、基本的に名詞を使用します。

/api/channels
/api/messages

リソースが集合である場合、その中に含まれる個々のリソースを表す場合には、集合のリソースを表すパスに続けて識別する値を含めたパスとします。

/api/messages/:id

リソースが別のリソースの子リソースであることを表す場合には、親リソースを含めたパスとします。なお、実際の管理上は親子関係となるリソースであってもパスで子リソースであることを表す必要がなければ、親リソースは含めないパスとしてもよいでしょう。

例えばメッセージリソースにはチャンネルリソースの子としての関係がある場合、次に示すAのようにチャンネルリソースをパスの上位に含めてもBのようにチャンネルリソースを含めなくても、どちらでもよいでしょう。

A. /api/channles/:name/messages/:id
B. /api/messages/:id

リソースで表すのが困難な場合、次のように動詞を使用して操作を表すパスとすることもあります。ただし、基本的にはリソースで表すものとするため、安易には使用しないでください。

/api/signup

HTTPメソッド

RESTの定義に沿って、リソースに対する操作を表すものとして使用します。主な操作としては次のものを使用します。

メソッド名	説明
GET	リソースの取得
POST	リソースの新規登録
PUT	既存リソースの更新
DELETE	リソースの削除
PATCH	リソースの一部変更

パスがリソースではなく操作を表す場合、「操作する」ためのメソッドとしてPOSTを使用します。

Note

CORSを使用する場合はプリフライトリクエストでOPTIONSを使用しますが、ブラウザが自動的に発行するリクエストであるため、主な操作には含めていません。 CORSについてはCORS（オリジン間リソース共有）を参照してください。

HTTPステータスコード

HTTPの仕様に沿って、HTTPステータスコードを使用します。

主に次のものを使用します。

ステータスコード	意味
200 - 299	成功
400 - 499	クライアントサイドに起因するエラー
500 - 599	サーバーサイドに起因するエラー

なお、リクエストが成功した場合のステータスコードとしてはレスポンスボディがあれば200（OK）、なければ204（No Content）を使用します。 POST等により新しいリソースが作成された場合には201（Created）およびLocationヘッダの使用が考えられますが、フレームワークによっては201を返すのが煩雑なコードになる場合があります。フロントエンドでハンドリングするための情報として200で必要十分であれば201は使用しなくても良いでしょう。

参考資料

HTTPレスポンスステータスコード - MDN

データフォーマット

リクエストおよびレスポンスのデータフォーマットはJSONとします。ただし、ファイルアップロード用のデータ送信時にはマルチパートを使用します（ファイルアップロードを参照）。また、ファイルダウンロード用のデータ送信時には任意のフォーマットを使用します（ファイルダウンロードを参照）。

日時については文字列で扱うこととし、ISO 8601（拡張形式）に準じたフォーマットとします。

参考資料

ISO 8601 | Wikipedia

エラー情報

ステータスコードでエラーの種類を判別できない場合はレスポンスボディにエラー情報を含めることを検討してください。

成功時と同じように処理するため、エラー時のレスポンスボディもJSON形式とし、エラーコードやエラーメッセージを含めると良いでしょう。例を示します。

{
  "code": 123,
  "message": "xxxの値が不正です"
}

バージョニング

REST APIを変更する際は、なるべく後方互換性を保つのが望ましいです。変更におけるいくつかのユースケースと後方互換の有無を例示します。

ユースケースの例	後方互換の有無
新しいAPIを追加する	新規追加なので既存APIに影響はなく、後方互換あり
既存のAPIに渡す値へ新しい項目を追加する	デフォルト値を用意すれば後方互換性を保てる
既存のAPIから返される値に項目を追加する	既存の項目がなくなるわけではないので後方互換あり
既存のAPIの振る舞いが変わる	後方互換なし
既存のAPIを廃止する	後方互換なし

後方互換性を崩す変更を伴う場合、一例としてパスによるバージョニングがあります。パスのルートにバージョン番号を含めて、各API毎ではなくAPI全体をバージョニングします。

既存のAPIのルートパス - /api/v1
後方互換性を崩さない変更であれば、このルートパスを使い続ける
後方互換性を崩す新しいAPIのルートパス - /api/v2
次に後方互換性を崩す変更が入るまでは、このルートパスを使う

なお、REST APIの公開範囲が自分たちの管理下にあればクライアントアプリケーションの変更も管理できるため、REST API単体でのバージョニングは行わなくても良いでしょう。

参考資料

Representational State Transfer - Wikipedia

※ このドキュメントはFintan コンテンツ使用許諾条項の下に提供されています。

※ このドキュメントに記載されている会社名、製品名は、各社の登録商標または商標です。