PUTメソッドはHTTP基本的なメソッドの1つとして、多くの場合に利用される必要があります。本文では、PUTメソッドの特徴、仕組みなどを詳しく解説した上、非常に使いやすいAPIクライアントでPUTリクエストを実装する方法を皆さんに紹介していきたいと思います。
PUTメソッドとは
PUTメソッドはHTTPの基本的なメソッドの1つとして、主にリソースのデータ全置換のために利用されるメソッドです。PUTメソッドのデータ送信方法は、POSTメソッドと同じようにHTTPリクエストボディにデータを追加して送信することになります。PUTメソッドを使う場合、リクエストのURIは更新対象のリソースを特定する必要があります。
PUTメソッドの主な特徴
PUTはリソースの完全な更新に用いられるイデンポテントなメソッドとして、主に以下の特徴があります:
リソースの更新/作成に使用
PUTは対象のリソースを更新するために使われます。リソースが存在しない場合は、新しく作成します。
イデンポテント性あり
同じリクエストを複数回実行しても、結果は同じになります。 PUTはリソースを上書きする性質があるため、リクエストの回数に関係なく結果は変わりません。
リクエストボディにデータを含む
更新するデータや新規リソースの内容は、リクエストボディに含まれて送信します。
全リソースを更新
PUTはリソース全体を上書きします。部分的な更新にはPATCHが利用されます。
URIはリソースを特定
PUTリクエストのURIは、更新対象のリソースを指定する必要があります。
冪等性あり
同じリクエストを何回送信しても、リソースの状態が変わらないことを冪等性といいます。PUTにはこの性質があります。
このように、PUTはリソースの完全な更新に用いられるイデンポテントなメソッドです。
PUTメソッドとリクエストの使用例
PUTメソッドは、GETやPOSTメソッドのように汎用されていないにも関わらず、PUTメソッドの使用が必要となる場面も非常に多くなっています。次は、PUTメソッドとリクエストが必要となる場合を皆さんに紹介します。
REST APIでのリソースの更新
PUT /users/1
{
"name": "John Smith",
"age": 35
}
指定したURIのユーザー情報をリクエストボディの内容で上書き更新します。
ファイルのアップロード
PUT /files/report.pdf
<file data>
指定のファイルパスに、リクエストボディのバイナリデータをアップロードします。
データベースレコードの更新
UPDATE table SET
column1 = value1,
column2 = value2
WHERE id = 1;
主キーで指定したレコードを、リクエストボディの値で更新します。
リソースの作成
PUT /users/2
{
"name": "Jane Doe",
"age": 28
}
ユーザー2が存在しなければ、リクエストボディのデータで新規作成します。
このように、REST APIではリソースの更新に、ファイルアップロードでは完全な上書きに、PUTメソッドが利用されます。URIでリソースを特定し、ボディに新しいデータを含めるのがポイントです。
PUTとPOSTメソッド：共通点と相違点
上記のPUTメソッドの解説から、多くのユーザーは、PUTメソッドとPOSTメソッドとは一緒ではないのかと思っているかもしれません。確かに、PUTとPOSTはともにサーバー上のリソースを更新するHTTPメソッドですが、実際には、次のような共通点と相違点があります。
PUTとPOSTとの共通点
- リクエストボディを送信できる
- 特定のリソースに対する操作を表す
- 冪等性がない(複数回リクエストしても結果が変わる)
PUTとPOSTとの相違点
- PUTはリソースの完全な更新、POSTは部分的な更新に使われる
- PUTはイデンポテント、POSTは非イデンポテント
- PUTはURIでリソースを指定、POSTはURIでは処理を指定
- PUTはリソースがなければ作成、POSTは常に新規作成
- PUTは200または204を返す、POSTは201を返す
PUTは既存リソースの全置換、POSTは新規作成や部分更新に使い分けられます。 URIの意味付けやレスポンスコードも異なります。PUTとPOST両者の違いを理解し、目的に応じて使い分けることも重要です。
Apidog：１クリックでPUTリクエストを送信可能！
それでは、もしPUTリクエストを送信してリソースのデータを更新したりする必要がある場合は、どうやって実装すればいいですか？この部分では、日本語対応API管理ツールのApidogで１クリックだけでPUTリクエストを送信できる方法を皆さんに紹介します。Apidogを使って、PUTリクエストを送信すると、送信情報と取得結果を一緒に保存して、API仕様書を作成して、簡単に他のメンバーに共有することも可能になりますので、非常に便利です。
ApidogでPUTリクエストを送信する場合、PUTリクエストのパラメータ、Body、Headerの設定は、Apidogで全部利用することができますし、Bodyでform-data、x-www-form-urlencoded、json、xml、rawやbinaryなどのフォーマットでデータを渡すこともできるので、非常に便利です。
