APIにおいて、URIとともにGETやDELETEといったHTTPメソッドを使用します。 GETやDELETEはそれぞれ意味がすぐにわかりますが、POST、PUTやPATCHおよびそれらの差異となるとたまに思い出すために時間がかかるため、備忘を兼ねメモします。
分類
- GET
- リソースの取得
- POST
- リソースの新規生成
- PUT
- 作成済みリソースの置き換え
- PATCH
- 作成済みリソースの修正
- DELETE
- 作成済みリソースの削除
- HEAD
- メタデータの確認
各論
以下で https://sample.com/api/v1/items/
リクエストを例に各論を見ていきます。
GET
リソースを取得します。
https://sample.com/api/v1/items/${item_id}
の形でidを用いて一意に限定して取得するか、https://sample.com/api/v1/items
でリストを取得することが多いかと思います。
GETはあくまでリソースの取得を行い、リソース自体への修正や削除は実施しません。(ただし、既読などの情報取得に応じた状態の変更はこの限りではなさそうです)
POST
リソースの新規生成を行います。
https://sample.com/api/v1/items
の形式でリクエストを行い、対応するリソースの生成を行います。
RFC7231に記述されているように、リソース生成によって作成されたidを返却する場合が多いように思います。
つまり、 https://sample.com/api/v1/items
によってitemが生成され 12345というidが採番された場合は 12345を返却します。
POST 要請が成功裡に処理された結果,生成元サーバ上にて一つ以上のリソースが作成された場合、生成元サーバは,次を包含する 201 (Created) 応答を送信するべきである:[ 作成された主たるリソース用の識別子 ]を供する Location ヘッダ,新たなリソース(たち)を指しつつ, 要請の状態°も述べるような,表現。
PUT
指定したURIにおける情報を更新します。
この際に、部分的に更新するのではなく、新しいリクエストに含まれる値で置換します。すなわち、下記リソースに対し、 https://sample.com/api/v1/items/12345
のリクエストで
name = "sample" category = "sample"のようにリクエストし、12345で表されるリソースを上書きし200(OK)か204(No Content)を返却します。
また、該当URIのリソースが存在しない場合は新規リソースを生成し、201(Created)を返却します。
{ "id" : "12345", "name": "hoge", "category": "fuga" }
PATCH
指定したURIにおける情報の部分更新を行います。
先ほどのPUTではURIに存在するリソースを新しいリソースで置換していましたが、本メソッドではリソースの一部分を上書きします。
例えば、PUT
でのリソースの場合に https://sample.com/api/v1/items/12345
name = "sample"のようにリクエストし、下記のように該当リソースを修正します。
{ "id" : "12345", "name" : "sample", "category" : "fuga" }
DELETE
指定したURIのリソースを削除します。 レスポンスのステータスコードは下記のように定義されています。(RFC7231より)
動作は成功する見込みが高いが、まだ実行済みでない場合 : 202 (Accepted) 動作は実行済みで、更なる情報は給されない場合 : 204 (No Content) 動作は実行済みで、応答メッセージが[ その状態°を述べる表現 ]を内包する場合 : 200 (OK)
HEAD
GETリクエストとほぼ同じですが、ヘッダーのみ返却されます。 また、ヘッダーの内容のうち、ペイロードヘッダーは省略されえます。
まとめ
HTTPメソッドに関してそれぞれの役割について簡単にまとめました。 POSTは実際はもっと多様に扱われますが、一つのリソースに対する扱い方という観点から整理しています。 調べる中でRFCが参考になりましたので、一度ご確認いただけますと幸いです。
参考
- RFC7231 - HTTP/1.1: 意味論と内容
- http method 全般に関する記載があります。
- RFC 5789 — PATCH Method for HTTP
- patchメソッドに関する記載があります。