REST API を使用すると、あらゆる種類の CRUD (作成、取得、更新、削除) 操作を持つ Web アプリケーションを開発することができます。 REST ガイドラインでは、サーバーへの特定のタイプの呼び出しに特定の HTTP メソッドを使用することを推奨しています (技術的にはこのガイドラインに違反することは可能ですが、非常に推奨されません)。 GET リクエストはリソースの状態を変更しないので、これらは安全なメソッドと言われています。 さらに、GET APIはべき乗であり、複数の同一のリクエストを行うことは、他のAPI（POSTまたはPUT）がサーバ上のリソースの状態を変更するまで、毎回同じ結果を生成しなければならないことを意味する。
任意の HTTP GET API について、リソースがサーバー上で見つかった場合、HTTP レスポンスコード 200 (OK) – 通常 XML または JSON コンテンツ (プラットフォーム非依存のため) であるレスポンスボディとともに – を返さなければなりません。 同様に、GET リクエスト自体が正しく形成されていないと判断された場合、サーバーは HTTP レスポンスコード 400 (BAD REQUEST) を返します。
リクエスト URI の例
- HTTP GET http://www.appdomain.com/users
- HTTP GET http://www.appdomain.com/users?size=20&page=5
- HTTP GET http://www.appdomain.com/users/123
- HTTP GET http://www.appdomain.com/users/123/address
HTTP POST
POST APIを使って例えば新しい下位のリソースを作成することができる。 例えば、ファイルはそれを含むディレクトリに従属し、行はデータベース テーブルに従属します。 厳密にRESTの観点から話すと、POSTメソッドはリソースのコレクションに新しいリソースを作成するために使用されます。
理想的には、リソースがオリジンサーバーに作成された場合、応答はHTTP応答コード201 (Created)であるべきで、リクエストのステータスを記述し、新しいリソースを参照するエンティティ、およびLocationヘッダーを含みます。
多くの場合、POSTメソッドが行ったアクションがURIによって識別できるリソースにならないかもしれません。 この場合、HTTP レスポンスコード 200 (OK) または 204 (No Content) のいずれかが適切なレスポンスステータスです。
このメソッドへのレスポンスは、適切な Cache-Control または Expires ヘッダーフィールドを含まない限り、キャッシュ可能ではないことに注意してください。
リクエストURIの例
- HTTP POST http://www.appdomain.com/users
- HTTP POST http://www.appdomain.com/users/123/accounts
HTTP PUT
PUT APIは主に既存のリソースを更新するために使用します（リソースが存在しない場合、新しいリソースを作成するかしないかはAPIの判断に委ねられます）。 PUT API によって新しいリソースが作成された場合、オリジンサーバーはHTTPレスポンスコード 201 (Created) 応答によってユーザーエージェントに通知しなければならず、既存のリソースが変更された場合、リクエストの正常終了を示すために 200 (OK) または 204 (No Content) 応答コードのいずれかが送られるべきです。
要求がキャッシュを通過し Request-URI が一つまたは複数の現在キャッシュされているエンティティを特定した場合、それらのエントリは stale として扱われるべきです (SHOULD)。 このメソッドへのレスポンスはキャッシュされません。
リクエストURIの例
- HTTP PUT http://www.appdomain.com/users/123
- HTTP PUT http://www.appdomain.com/users/123/accounts/456
HTTP DELETE
その名のとおり、DELETE API はリソース (Request-URI により特定) の削除に使用されるものです。
DELETE リクエストの成功した応答は、応答にステータスを記述するエンティティが含まれる場合は HTTP 応答 code 200 (OK)、アクションがキューに入れられた場合は 202 (Accepted)、アクションは実行されたが応答にエンティティが含まれない場合は 204 (No Content) であるべきである（SHOULD）。 リソースを DELETE すると、そのリソースはリソースのコレクションから削除されます。 そのリソースに対して DELETE API を繰り返し呼び出しても結果は変わりません。しかし、リソースに対して 2 回目に DELETE を呼び出すと、それはすでに削除されているので 404 (NOT FOUND) を返します。 これはDELETEメソッドを非べき等なものにしてしまうという意見もあるかもしれません。 これは議論と個人的な意見の問題です。
要求がキャッシュを通過し、Request-URI がひとつまたは複数の現在キャッシュされているエンティティを特定する場合、それらのエントリは stale として扱われるべきです (SHOULD)。
リクエスト URI の例
- HTTP DELETE http://www.appdomain.com/users/123
- HTTP DELETE http://www.appdomain.com/users/123/accounts/456
HTTP PATCH
HTTP PATCH 要求はリソースに対して部分更新するためのもので、その要求内容は次のとおりです。 PUT リクエストもリソースのエンティティを変更するので、より明確にするために、PATCH メソッドは既存のリソースを部分的に更新するための正しい選択であり、PUT はリソースを完全に置き換える場合にのみ使用されるべきです。 IE8、PHP、Tomcat、Django、および他の多くのソフトウェアでは、PATCH のサポートがないか、壊れています。
HTTP GET /users/1
は以下のようなレスポンスを返します:
{id: 1, username: 'admin', email: ''}
メールを更新するパッチ要求のサンプルは次のようになります:
HTTP PATCH /users/1
” }
]
HTTP仕様では、次の操作が可能な場合があります。
},
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
{ "op": "copy","from": "/a/b/d", "path": "/a/b/e" }
]
PATCHメソッドはPOSTやPUTメソッドを置き換えるものではありません。 リソース全体を置き換えるのではなく、差分 (diff) を適用します。
Summary of HTTP Methods for RESTful APIs
以下の表は、上で述べた HTTP メソッドの使用方法をまとめたものです。 /users)
Glossary
Safe Methods
HTTP 仕様では、GET および HEAD はリソース表現の取得にのみ使用すべきです – そしてこれらはサーバー上のリソースを更新/削除するものではありません。
これにより、ユーザエージェントは POST、PUT、DELETE などの他のメソッドを独自の方法で表現し、安全ではないアクションが要求されている可能性があるという事実をユーザに認識させ、サーバ上のリソースを更新/削除できるため、慎重に使用すべきとされています。
Idempotent Methods
idempotent という用語は、1 回または複数回実行しても同じ結果を生成する操作を説明するために、より包括的に使用されます。 意図しない効果を引き起こすことなく、必要な回数だけ操作を繰り返したり再試行できることを意味するため、べき等性は多くの状況で便利な特性である。 HTTP 仕様では、GET、HEAD、PUT、DELETE の各メソッドがべき等メソッドと宣言されています。 その他のメソッドOPTIONSとTRACEは副作用を持つべきではありませんから、どちらも本質的にべき等です。