PUT vs PATCH REST API メソッド: どちらを選ぶべき?

RESTに準拠した設計では、PUTとPATCHはサーバー上のリソースを更新するための2つのHTTPメソッドです。ただし、REST APIにおけるPUT対PATCHの違いは、更新の実行方法と各メソッドが最適なシナリオにあります。どちらのメソッドも既存データの変更を目的としていますが、REST APIにおけるPUT対PATCHの違いを理解することで、開発者は実行する更新の性質に基づいて最適な選択ができます。このブログ記事では、REST APIにおけるPUT対PATCHの違い、特にPATCH対更新RESTの議論、各メソッドを使う場面、さまざまなユースケースに適したメソッド選択のガイダンスを解説します。

REST APIのPUTとは何ですか？
REST APIのPATCHとは何ですか？
REST APIにおけるPUT対PATCHのべき等性
- PUTメソッドとべき等性
- PATCHメソッドとべき等性
例: REST APIs での PUT と PATCH の比較
まとめ: REST APIs での PUT と PATCH の主な違い
最後に

REST APIのPUTとは何ですか？

REST APIs での PUT と PATCH の違いを理解するには、まず PUT が何かを知る必要があります。セクション9.6 RFC 2616によると、REST API の PUT メソッドは、指定された Request-URI にエンティティを保存することをリクエストします。

Request-URI が既存のリソースを指す場合、エンティティはオリジンサーバーに存在するリソースの変更版と見なされるべきです。Request-URI が既存のリソースを指さず、そのリソースをユーザーエージェントが新規作成できる場合、オリジンサーバーはそのリソースを作成できます。

つまり、PUT メソッドはサーバー上のリソース全体を更新するために使われます。これにより PUT はより「完全な」更新となり、リソース全体の置換が必要な場合に用いられることがよくあります。

PUT は以下のユースケースに最適です:

完全なリソースを更新する (例: すべての新しい情報を含むユーザープロフィールを更新する)。
アイテムまたはレコード全体を置換する。
リソースのアイデンティティが明確で、データ全体をリフレッシュする必要がある場合。

I'd be happy to help translate, but the text "In systems like" appears incomplete. Could you please provide the full text you'd like translated to Japanese? Elasticsearchべき等操作はデータの一貫性を保証するために必須です。例えば、Elasticsearch でドキュメントを PUT で更新すれば、同じリクエストを繰り返しても予期しない副作用がないことが保証されます。

REST APIのPATCHとは何ですか？

PUT について説明したので、次に REST APIs での PATCH が何か、どのように機能するか、そして PUT と PATCH を比較する前に確認しましょう。 RFC 5789によると、REST API の PATCH メソッドは、リクエストエンティティに記述された変更セットを Request-URI で識別されるリソースに適用することをリクエストします。

これは PUT と PATCH の REST API における区別と一致しており、変更が必要なデータだけを送信し、サーバーがそれらの変更を既存のリソースに適用し、リソース全体は変わらないままです。開発者はこれらの段階的な変更を表すパッチを作成することが多く、最小限のデータ転送と効率的な更新を確保しています。

このため、REST API の PATCH メソッドは以下のユースケースに適しています:

リソース内の特定フィールドのみを更新する (例: ユーザーのメールアドレスまたは電話番号を変更する)。API での PATCH の例は、新しいメールアドレスだけを送信し、他のフィールドはそのままにする場合があります。
データペイロードを最小化してパフォーマンスを向上させる。
リソース全体を置換するのではなく、段階的に更新したい場合。
単一フィールドの変更 (ユーザーのメールアドレスの変更など) など、特定フィールドの変更をカプセル化するパッチを作成し、関連のないデータに影響を与えません。

以下のようなプラットフォーム: ヘッドレスCMS が複雑なコンテンツ構造を扱うことが多い場合、単一フィールドの変更など小規模な更新に PATCH を使用することで、サーバー負荷を軽減しパフォーマンスを向上させることができます。

この 2 つのメソッドについて説明したので、REST APIs での PUT と PATCH が何かについて基本的な理解ができたはずです。ただし、REST APIs での PUT と PATCH の違いを説明する前に、これら 2 つのメソッドのべき等性について説明する必要があります。

REST APIにおけるPUT対PATCHのべき等性

REST APIでは、べき等性とは、同じ入力で何度繰り返しても同じ結果が得られる操作の性質を指します。つまり、同じリクエストを複数回送信しても、実行回数に関わらずサーバーへの影響は変わりません。これはAPIの安定性と予測可能性を確保するうえで重要です。では、REST APIのPUTメソッドとPATCHメソッドの違いにどう関連するのでしょうか。

PUTメソッドとべき等性

REST APIのPUTメソッドは常にべき等です。なぜなら、指定されたURIのリソース全体を、リクエストで提供されたデータで置き換えるように設計されているためです。つまり、同じリソースデータでPUTリクエストを複数回実行しても、結果は常に同じになります。

PUTがべき等な理由は何か。PUTリクエストを送信するときは、本質的にサーバーに「このリソースの完全で正確な状態がこれだ」と伝えています。PUTリクエストを1回送信しても複数回送信しても、結果のリソースは常に同じです。

例えば、ユーザーのメールアドレスを更新する場合を考えます。同じPUTリクエストを複数回送信しても、毎回同じデータでリソースが置き換わるため、結果は変わりません。

例:

PUT /users/1{"username": "john_doe","email": "[email protected]"}

このリクエストを複数回送信しても、結果は常に同じです:

{"username": "john_doe","email": "[email protected]"}

ユーザーのデータが既にこの状態でも、再度リクエストを送信しても何も変わりません。同じデータでデータを置き換えるので、リクエストの効果は何度繰り返しても変わりません。これがPUTをべき等にしている理由です。

PATCHメソッドとべき等性

一方、REST APIのPATCHメソッドは、一般的にはべき等ですが、より柔軟です。パッチを作成するときは、操作がべき等であることを確認します(例: 値を設定する)。意図しない副作用を避けるため、繰り返されたリクエストに注意が必要です。PATCHがべき等かどうかは、操作と変更されるデータに依存します。

PATCHがべき等な理由は何か。PATCHリクエストの場合、べき等性は同じパッチを複数回適用しても同じ結果が得られることを意味します。これはパッチ自体が繰り返し適用されてもニ次的な副作用や変更を引き起こさない限り成り立ちます。同じデータで同じパッチを何度も適用しても、最初の適用後は結果は変わりません。

例えば、ユーザーのメールアドレスだけを更新する場合、同じPATCHリクエストを繰り返し送信しても、最初の実行以降は結果は変わりません。複数回リクエストを送信しても、ユーザーのメールアドレスは同じままで、リソースの状態は変わりません。

PATCH APIの例:

PATCH /users/1{"email": "[email protected]"}

メールアドレスが既に[email protected]の場合、このPATCHを再度適用してもベ変わらず、べき等になります。

ただし、特定のケースではPATCHはべき等でない場合もあります。例えば、PATCH操作がカウンターを変更したり、リスト項目を追加したり(数値をインクリメントするか、配列に追加する)する場合、同じPATCHを繰り返し適用すると異なる結果になる可能性があります。これはべき等性の原則に違反します。

べき等でないAPI REST PATCHの例:

PATCH /counter/1{"increment": 1}

このPATCHを繰り返し適用すると、カウンターは増加し続け、毎回異なる値になります。これはべき等ではありません。なぜなら、結果が適用するたびに変わるからです。

これで基本を理解できたので、PUT vs PATCHの違いをよく理解するための具体的なシナリオを見てみましょう。

例: REST APIs での PUT と PATCH の比較

理論はここまでにして、べき等操作と非べき等操作を含む例を交えて、PUTとPATCHの違いを見ていきます。

シナリオ1: PUTリクエスト。リソース全体の置き換え

eコマースシステムで製品を管理するAPIエンドポイントを想像してください。製品名、価格、説明を含む製品の詳細をすべて更新する必要があります。これはHTTPメソッドのPUT vs PATCHの典型的な例で、PUTは完全な製品リソースを置き換えるのに使用されます。

初期製品

GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."}

製品の価格と説明を更新したいとします。リソース全体を含むPUTリクエストを送信します:

PUTリクエスト：

PUT /products/1001{"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."}

このPUTリクエストを1回または複数回実行しても、結果は常に同じです。商品の詳細が新しい価格と説明で更新され、毎回同じ結果が得られます。これはPUTのべき等性を保証します。

結果（PUTリクエスト後）:

{"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."}

シナリオ2: PATCHリクエスト - リソースの一部を更新する

次に、商品の説明など、リソースの一部のみを更新するPATCHリクエストを考えます。PATCH APIの例：商品の説明は変更したいが、価格は変更したくない場合、PATCHが適切な選択肢です。これを実装するには、説明など変更が必要なフィールドのみを含むパッチを作成します。このAPI REST PATCHの例では、説明フィールドのみを含めます。

初期製品

GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."}

PATCH リクエスト：

PATCH /products/1001{"description": "A lightweight, powerful laptop."}

このPATCHリクエストを送信すると、descriptionフィールドのみが更新されます。同じPATCHリクエストを複数回送信しても、最初の更新後は説明は変わらないままになり、リクエストがべき等になります。

結果（PATCHリクエスト後）:

{"id": 1001,"name": "Laptop","price": 999.99,"description": "A lightweight, powerful laptop."}

同じPATCHを再度適用しても、商品の説明は最初のPATCH後と同じままです。結果が一貫しているため、このシナリオではPATCHはべき等です。

シナリオ3: PATCHリクエスト - べき等でない操作

べき等でないPATCH操作を見てみましょう。ユーザーのウォレット残高用のエンドポイントがあり、残高を増やしたいとします。PUTとPATCHの違いの例をここで示せます：PATCHは毎回残高に値を追加します。

初期ウォレット

GET /users/1/wallet{"id": 1,"balance": 100.00}

PATCH リクエスト：

PATCH /users/1/wallet{"increment": 50.00}

このPATCHリクエストはウォレット残高を50ドル増やします。このPATCHリクエストを複数回送信すると、毎回のPATCHで残高が増え続け、毎回異なる結果になります。これはべき等でありません。なぜなら、同じPATCHを繰り返し適用すると、毎回異なる結果になるからです。

結果（最初のPATCHリクエスト後）:

{"id": 1,"balance": 150.00}

結果（2番目のPATCHリクエスト後）:

{"id": 1,"balance": 200.00}

ここでは、PATCHはべき等ではありません。同じデータでリクエストを繰り返すと、毎回異なる結果が得られます。

まとめ: REST APIs での PUT と PATCH の主な違い

PUT対PATCHの主な違い（REST API）は、更新の処理方法です。PUTはリソース全体を置き換えるため、欠落しているフィールドは消去され、データ損失につながる可能性があります。これが開発者が部分更新用のパッチを作成する理由です。変更されていないフィールドを上書きしないようにし、データの整合性を維持するためです。

これはPATCHを部分更新でより効率的にします。PATCH APIの例は、ユーザーのメールアドレスだけを更新したい場合、パッチはメールフィールドのみを送信します。一方、PUTリクエストはユーザーデータ全体が必要です。

PUTでは、完全なデータペイロードが必要です。つまり、すべてのフィールドを送信する必要があり、欠落しているフィールドは消去されます。一方、PATCHは更新が必要なフィールドのみを送信するため、より効率的です。特に、変更が少ない大きなリソースの場合に有効です。REST APIのPATCHメソッドにより、より焦点を絞った小さなリクエストが可能になり、データ転送量が削減されます。

PUTとPATCHはどちらもべき等です。つまり、同じリクエストを繰り返しても、同じ結果が得られます。ただし、PUTはリソース全体を置き換えるため、より予測可能です。PATCHを使用して指定されたフィールドのみを変更する場合、サーバーが更新を処理する方法によっては異なる結果になる可能性があります。

例えば、PATCHがカウンターをインクリメントする場合、リクエストを繰り返すと異なる結果になる可能性があります。ただし、PATCH API操作もべき等になるように設計できます。

結論として、REST APIのPUT対PATCHの違いは、更新の性質に帰着します：PATCHは部分的な変更用であり、PUTは完全なリソース置き換え用です。どちらもべき等ですが、PATCHはより複雑な場合があります。

最後に

PUTとPATCHはどちらもREST API設計の基本的なHTTPメソッドですが、異なる目的を果たします。これはREST APIのPUT対PATCHの違いの本質です。この記事で取り上げた例でPUTとPATCHの違いを理解することで、APIの効率性、明確性、機能を大幅に向上させることができます。ユースケースに基づいて正しいメソッド（PATCH対更新REST）を選択することで、APIをより効率的で保守しやすく、ユーザーフレンドリーにできます。常に更新の性質（完全か部分か）とパフォーマンスおよびデータの整合性への影響を考慮し、ニーズに最適なメソッドを選択してください。