本文へスキップ
Hironobu Iga

API における HTTP メソッドの分類と意味

GET / POST / PUT / PATCH / DELETE / HEAD をリソース操作の観点で分類し、とくに紛らわしい POST・PUT・PATCH の違いを整理した備忘です。

公開日

この記事は別サイトにも掲載しています。 https://iganin.hatenablog.com/entry/2020/08/10/210711

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 の形式でリクエストを行い、対応するリソースの生成を行います。 RFC 7231 に記述されているように、リソース生成によって作成された 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 のリソースを削除します。 レスポンスのステータスコードは下記のように定義されています。（RFC 7231 より）

動作は成功する見込みが高いが、まだ実行済みでない場合 ： 202 (Accepted)
動作は実行済みで、更なる情報は給されない場合 ： 204 (No Content)
動作は実行済みで、応答メッセージが［ その状態°を述べる表現 ］を内包する場合 ： 200 (OK)

GET リクエストとほぼ同じですが、ヘッダーのみ返却されます。 また、ヘッダーの内容のうち、ペイロードヘッダーは省略されえます。

まとめ

HTTP メソッドに関してそれぞれの役割について簡単にまとめました。 POST は実際はもっと多様に扱われますが、一つのリソースに対する扱い方という観点から整理しています。 調べる中で RFC が参考になりましたので、一度ご確認いただけますと幸いです。

参考

続けて読む