RESTful API 設計では、PUT と PATCH はサーバー上のリソースを更新するために使用される 2 つの HTTP メソッドですが、REST API における PUT と PATCH の違いは、更新を実行する方法と、それぞれが最適なシナリオにあります。どちらのメソッドも既存のデータを変更するように設計されていますが、REST API の PUT と PATCH の違いを理解すると、開発者が実行する必要がある更新の性質に基づいて最適な選択を行うのに役立ちます。このブログ投稿では、REST API における PUT と PATCH の違いを検討し、PATCH と REST 更新の議論、いつそれぞれを使用するかに焦点を当て、さまざまなユースケースに適切な方法を選択するためのガイダンスを提供します。
REST API の PUT とは何ですか?
REST API における PUT と PATCH の違いを理解するには、まず、そもそも PUT とは何なのかを知る必要があります。に基づく セクション 9.6 RFC 2616、REST API の PUT メソッドは、囲まれたエンティティが指定された Request-URI に保存されることを要求します。
Request-URI が既存のリソースを参照している場合、囲まれたエンティティは、オリジン サーバー上に存在するエンティティの修正バージョンと見なされるべきです(SHOULD)。 Request-URI が既存のリソースを指しておらず、その URI が要求元のユーザー エージェントによって新しいリソースとして定義できる場合、オリジン サーバーはその URI を使用してリソースを作成できます。
つまり、PUT メソッドはサーバー上のリソース全体を更新するために使用されます。これにより、PUT はより「完全な」更新となり、リソースの完全な置換が必要な場合によく使用されます。
したがって、PUT は次の使用例に最適です。
- 完全なリソースを更新する (例: すべての新しい情報を使用してユーザー プロファイルを更新する)。
- 項目またはレコード全体を置き換えます。
- リソースの ID が明確で、そのデータを完全に更新する必要がある場合。
のようなシステムでは、 エラスティックサーチ、データの一貫性を保証するには冪等操作が必要です。たとえば、PUT を使用して Elasticsearch のドキュメントを更新すると、意図しない副作用が生じることなく同じリクエストを繰り返すことができます。
REST APIのPATCHとは何ですか?
REST API での PUT について説明したので、REST API での PUT と PATCH を比較する前に、REST API での PATCH とは何か、そしてそれがどのように機能するかを見てみましょう。で定義されているように、 RFC 5789、REST API の PATCH メソッドは、リクエスト エンティティに記述されている一連の変更を Request-URI で識別されるリソースに適用することをリクエストします。
これは、PUT と PATCH REST API の区別と一致しています。つまり、変更が必要なデータのみを送信し、サーバーはリソース全体を変更することなく、それらの変更を既存のリソースに適用します。開発者は多くの場合、これらの増分変更を表すパッチを作成し、最小限のデータ転送と効率的な更新を保証します。
そのため、REST API の PATCH メソッドは、次の使用例に適しています。
- リソース内のフィールドのサブセットのみを更新する (ユーザーの電子メール アドレスや電話番号の変更など)。 PATCH API の例では、他のフィールドを変更せずに、新しい電子メールのみを送信することが考えられます。
- データ ペイロードを最小限に抑えることでパフォーマンスが向上します。
- リソースを完全に置き換えるのではなく、段階的に更新したい場合。
- 無関係なデータに影響を与えることなく、ユーザーの電子メールの変更など、特定のフィールドの変更をカプセル化するパッチを作成します。
のようなプラットフォームの場合 ヘッドレスCMS 複雑なコンテンツ構造を処理することが多いため、単一フィールドの変更などの小規模な更新に PATCH を使用すると、サーバーの負荷が軽減され、パフォーマンスが向上します。
これら 2 つのメソッドを説明すれば、REST API における PUT と PATCH が何であるかについて十分に理解できるはずです。ただし、REST API における PUT と PATCH の違いについて説明する前に、これら 2 つのメソッドにおける冪等性について説明する必要があります。
PUT の冪等性と REST API のパッチ
REST API では、冪等とは、同じ入力で複数回繰り返されたときに同じ結果が得られる操作の特性を指します。これは、同じリクエストを複数回実行すると、実行回数に関係なく、サーバーに対して同じ効果が生じるはずであることを意味します。これは、API の安定性と予測可能性を確保するために重要です。しかし、それは REST API の PUT と PATCH の違いとどのように関係するのでしょうか?
PUT メソッドと冪等性
REST API の PUT メソッドは、指定された URI にあるリソース全体をリクエストで提供されたデータに置き換えるように設計されているため、常に冪等です。つまり、同じリソース データに対して PUT リクエストを複数回実行した場合、結果は常に同じになります。
PUT が冪等であるのはなぜですか? PUT リクエストを行うときは、基本的にサーバーに「これがこのリソースに必要な完全かつ正確な状態です」と伝えることになります。 PUT リクエストを 1 回発行しても複数回発行しても、結果として得られるリソースは常に同一になります。
たとえば、ユーザーの電子メール アドレスを更新するシナリオを考えてみましょう。同じ PUT リクエストを複数回実行しても、リソースは毎回同じデータに置き換えられるため、結果は変わりません。
例：
| PUT /users/1{“ユーザー名”: “john_doe”,”メール”: “[email protected]”} |
このリクエストを複数回送信すると、結果は常に同じになります。
| {“ユーザー名”: “john_doe”,”メール”: “[email protected]”} |
ユーザーのデータが既にこれである場合でも、再度リクエストを送信しても何も変わりません。データを同じデータに置き換えるので、何度繰り返してもリクエストの効果は変わりません。これが PUT をべき等にする理由です。
PATCH メソッドとべき等性
一方、REST API の PATCH メソッドも通常は冪等ですが、より柔軟性があります。パッチを作成するときは、繰り返しのリクエストによる意図しない副作用を避けるために、操作がべき等であることを確認してください (値の設定など)。 PATCH が冪等であるかどうかは、操作と変更されるデータによって異なります。
PATCH が冪等であるのはなぜですか? PATCH リクエストの場合、べき等とは、同じパッチを複数回適用しても同じ結果が得られることを意味します。これは、パッチ自体が繰り返し適用されたときに追加の副作用や変更を引き起こさない限り当てはまります。同じデータで同じパッチを適用し続ける場合、最初の適用後、結果は変わらないはずです。
たとえば、ユーザーの電子メールを更新するだけの場合、同じ PATCH リクエストを繰り返し送信しても、リクエストが複数回行われたとしても、初回以降の結果は変わりません。ユーザーのメールアドレスは変わりませんし、リソースの状態も変わりません。
PATCH API の例:
| PATCH /users/1{“電子メール”: “[email protected]”} |
電子メールがすでに [email protected] であった場合、この PATCH を再度適用しても変更は生じず、冪等になります。
ただし、場合によっては、PATCH が非冪等である場合もあります。たとえば、PATCH 操作でカウンターを変更したり、リストに項目を追加したりする場合 (数値のインクリメントや配列への追加など)、同じ PATCH を繰り返し適用すると、異なる結果が生じる可能性があります。これは冪等性の性質に違反します。
非冪等 API REST PATCH の例:
| PATCH /counter/1{「増分」: 1} |
この PATCH を繰り返し適用すると、カウンターは増加し続け、毎回異なる値になります。結果はアプリケーションごとに変わるため、これは冪等ではありません。
要点は理解できたので、REST API における PUT と PATCH の違いをよりよく理解するために、いくつかのシナリオ例を見てみましょう。
シナリオ例: REST API における PUT と PATCH
理論はさておき、冪等操作と非冪等操作の両方を含む例を使用して、PUT と PATCH の違いを見てみましょう。
シナリオ 1: PUT リクエスト – リソース全体を置き換える
電子商取引システムで商品を管理するための API エンドポイントを想像してください。製品の名前、価格、説明など、製品の詳細をすべて更新する必要があります。これは、HTTP メソッド PUT と PATCH の典型的な例であり、PUT は完全な製品リソースを置き換えるために使用されます。
初期製品:
| GET /products/1001{"id": 1001,"name": "ラップトップ","price": 999.99,"description": "強力なラップトップ。"} |
製品の価格と説明を更新したいと考えています。リソース全体を含む PUT リクエストを送信します。
PUT リクエスト:
| PUT /products/1001{"id": 1001,"name": "ラップトップ","price": 899.99,"description": "割引価格の強力なラップトップ。"} |
この PUT リクエストを 1 回または複数回実行すると、結果は常に同じになります。新しい価格と説明を反映するために製品の詳細が更新されますが、毎回同じ結果が発生します。これにより、PUT の冪等性が保証されます。
結果 (PUT リクエスト後):
| {"id": 1001,"name": "ラップトップ","price": 899.99,"description": "割引価格の強力なラップトップ。"} |
シナリオ 2: PATCH リクエスト – リソースの一部を更新する
ここで、説明など、製品の詳細の一部のみを更新する PATCH リクエストを考えてみましょう。 PATCH API の例: 製品の説明は変更したいが、価格は変更したくない場合は、PATCH がより良い選択です。これを実装するには、この API REST PATCH の例の説明のように、変更が必要なフィールドのみを含むパッチを作成します。
初期製品:
| GET /products/1001{"id": 1001,"name": "ラップトップ","price": 999.99,"description": "強力なラップトップ。"} |
パッチリクエスト:
| PATCH /products/1001{“説明”: “軽量で強力なノートパソコン。”} |
この PATCH リクエストを送信すると、説明フィールドのみが更新されます。同じ PATCH リクエストを複数回送信すると、最初の更新後も説明は変更されず、リクエストは冪等になります。
結果 (PATCH リクエスト後):
| {"id": 1001,"name": "ラップトップ","price": 999.99,"description": "軽量で強力なラップトップ。"} |
同じ PATCH を再度適用しても、製品説明は最初の PATCH 後と同じになります。結果は一貫しているため、このシナリオでは PATCH が冪等になります。
シナリオ 3: PATCH リクエスト – 非冪等操作
非冪等の PATCH 操作を見てみましょう。ユーザーのウォレット残高のエンドポイントがあり、残高を増分したいとします。 PUT と PATCH の違いの例を次に示します。 PATCH は毎回残高に値を追加します。
初期ウォレット:
| GET /users/1/wallet{“id”: 1,“balance”: 100.00} |
パッチリクエスト:
| PATCH /users/1/wallet{“増分”: 50.00} |
この PATCH リクエストにより、ウォレットの残高が 50 ドル増加します。この PATCH リクエストを複数回送信すると、PATCH ごとに残高が増加し続けるため、毎回異なる結果が生じます。同じ PATCH を繰り返し適用すると異なる結果が生じるため、これはべき等ではありません。
結果 (最初の PATCH リクエスト後):
| {“id”: 1,“残高”: 150.00} |
結果 (2 回目の PATCH リクエスト後):
| {“id”: 1,“残高”: 200.00} |
ここで、同じデータを使用してリクエストを繰り返すと異なる結果が生成されるため、PATCH は冪等ではありません。
要約: REST API における PUT と PATCH の主な違い
REST API における PUT と PATCH の主な違いは、更新の処理方法です。 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 をより効率的で保守しやすく、使いやすいものにすることができます。更新の性質 (完全か部分か) と、パフォーマンスとデータの整合性への影響を常に考慮し、ニーズに最も適した方法を選択してください。
