PUT vs PATCH — What's the Difference?

PUT replaces an entire resource with the representation provided in the request; PATCH applies a partial update, modifying only the specified fields.

Why they differ

• PUT is defined as idempotent and expects the full resource representation — fields omitted from the body may be reset to their defaults
• PATCH is designed for sending only the fields that changed, leaving everything else untouched

How to choose

• Use PUT when the client always has and sends the complete resource, such as replacing a settings object wholesale
• Use PATCH for partial updates, like changing just one field on a large object, which is far more common in real-world APIs

FAQ

Is PATCH idempotent?

Not guaranteed by spec — it depends on the operation. A PATCH that sets a field to an absolute value is idempotent; one that increments a value is not.