REST API

kc@example.com (kc kim) — Mon, 25 Dec 2017 19:03:56 +0900

RESTとは

RESTはRepresentational State Transferの略である。World Wide Webのような分散ハイパーメディアシステム向けのアーキテクチャスタイルであり、Roy Fielding氏が2000年の博士論文で紹介した。RESTの原則に従うシステムはRESTfulと呼ばれる。

RESTの特徴

統一インターフェース: URIで識別したリソースを、一貫した限定的なインターフェースで操作する。HTTP APIは特定のプラットフォームやプログラミング言語に依存しない。
ステートレス: 各リクエストには処理に必要な情報を含める。サーバーはリクエスト間でクライアントのセッション状態を保持する必要がない。
キャッシュ可能: RESTはHTTP基盤を利用するため、Last-Modified や ETag などのヘッダーによるキャッシュを活用できる。
クライアント・サーバー構造: クライアントとサーバーの役割を分離し、相互依存を減らす。
自己記述的メッセージ: リクエストやレスポンスは、処理方法を理解するために必要な情報を含む。
階層化システム: セキュリティ、負荷分散、暗号化、プロキシ、ゲートウェイなどを中間層として追加できる。
コードオンデマンド（任意）: JavaScriptなどの実行可能なロジックをサーバーから送信し、クライアントの機能を拡張できる。

RESTの構成要素

リソース

リソースは、サーバーに保存される識別可能な対象である。クライアントは /groups/{groupId}/users/{userId} のようなURIを通して状態を取得、変更する。リソース名には通常、users や groups のような名詞を使う。

メソッド

HTTPメソッドは、リソースに対する操作を表す。代表的なメソッドには GET、POST、PUT、DELETE がある。

リプレゼンテーション

リプレゼンテーションは、レスポンスとして送信されるリソースの表現形式である。1つのリソースをJSON、XML、テキストなどで表現できる。

HTTPメソッド

REST APIでは、一般にHTTPメソッドをCRUD操作へ対応させる。

HTTPメソッド	CRUD	コレクションの例 `/customers`	個別項目の例 `/customers/{id}`
`POST`	作成	`201 Created`、通常は `Location` ヘッダーを付ける	リソースがすでに存在する場合は `404 Not Found` または `409 Conflict`
`GET`	取得	`200 OK`、必要に応じてページング、ソート、フィルタリングを使う	`200 OK`、IDが不明なら `404 Not Found`
`PUT`	更新または置換	通常は `405 Method Not Allowed`	`200 OK` または `204 No Content`、不明なIDなら `404 Not Found`
`DELETE`	削除	通常は `405 Method Not Allowed`	`200 OK`、不明なIDなら `404 Not Found`

リソース命名規則

RESTのリソース命名には、2つの基本原則がある。

URIはリソースを表す。
HTTPメソッドはリソースに対する操作を表す。

リソースには名詞を使う

update のような操作をURIへ含めない。

GET /users/update/1  (X)
PUT /users/1         (O)

リソース名は複数形に統一する

URIパスの各要素には複数形の名詞を使う。

GET /user/329   (X)
GET /users/329  (O)

ファイル拡張子を含めない

表現形式の要求には Accept などのHTTPヘッダーを使う。

GET /users/345/profile.jpg                          (X)
GET /users/345/profile
Accept: image/jpeg                                  (O)

スラッシュで階層を表す

/ で階層を表し、末尾のスラッシュは避ける。

/users/{userId}/books/  (X)
/users/{userId}/books   (O)

リソース間の関係を表す

サブリソースを使って関係を表現できる。

/users/{userId}/friends
/users/{userId}/books
/users/{userId}/recommendations/books

パスには小文字を使う

URIパスはスキームとホスト以外で大文字と小文字を区別する。小文字に統一すると曖昧さを避けられる。

/Users/{userId}/Books  (X)
/users/{userId}/books  (O)

HTTPステータスコード

適切に設計されたREST APIは、意味のあるHTTPステータスコードを返す。

2xx 成功

コード	意味
`200 OK`	リクエストを正常に処理した。
`201 Created`	新しいリソースを正常に作成した。
`204 No Content`	リクエストは成功し、レスポンス本文は不要である。

3xx リダイレクト

コード	意味
`304 Not Modified`	クライアントがキャッシュした版からリソースが変更されていない。

4xx クライアントエラー

コード	意味
`400 Bad Request`	サーバーがリクエスト構文を理解できない。
`401 Unauthorized`	認証が必要であるか、認証に失敗した。
`403 Forbidden`	サーバーはリクエストを理解したが、アクセスを拒否する。
`404 Not Found`	要求したリソースが存在しない。

5xx サーバーエラー

コード	意味
`500 Internal Server Error`	リクエスト処理中にサーバーでエラーが発生した。

devkuma – REST API