Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 50 ยท Pydantic models and validation

PUT, PATCH and partial updates

Learn the difference between PUT and PATCH in FastAPI, build partial updates with model_dump(exclude_unset=True), write update helpers and keep PUT idempotent.

Sooner or later a client wants to change something that already exists. There are two honest ways to do it. PUT says "here is the complete new version of this resource"; PATCH says "change only these fields". They look similar but behave differently, and mixing them up is a classic source of bugs: a PATCH that accidentally wipes fields, or a PUT that silently keeps old values.

This lesson shows how to implement both in FastAPI with Pydantic, how to tell "the client sent null" apart from "the client sent nothing", and why PUT must be idempotent. It builds on response models, where you met Create, Read and Update schemas.

PUT or PATCH?

PUT Replace the whole resource. Missing fields are an error.
PATCH Change only what was sent. Everything else stays.

Both answer 200 with the new state, or 404 if it does not exist.

1 / 2

PUT: replace everything

With PUT the request body is a full representation, so you validate it with a model whose fields are required (usually the same one used for creation). Every field is overwritten, and the id stays whatever the URL says.

Python A PUT endpoint

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Look at the first result: the note was pinned, but the PUT didn't mention pinned, so the default False replaced it. That is correct PUT behavior, and exactly why PUT is dangerous for clients that only know part of the resource. A PUT with a missing required field is rejected with 422.

PATCH: change only what was sent

For PATCH you need a model in which every field is optional. The crucial step is separating "not sent" from "sent as null". Give each field a default of None and call model_dump(exclude_unset=True): it returns only the fields the client actually included.

Python A PATCH endpoint with exclude_unset

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The second request sends "color": null. Because exclude_unset keeps fields that were set, even to None, the color is cleared. The third request sends an empty object and changes nothing. Without exclude_unset you'd be forced to guess, and every omitted field would look like an order to erase it.

Don't use model_dump(exclude_none=True) for PATCH. It would make it impossible to set a field to null on purpose, and it can't tell "unchanged" from "cleared".

Validating the merged result

A patch can be valid on its own and still produce an invalid resource, for example one that violates a rule across fields. A robust approach is to merge the changes into a copy of the current data, then validate the whole thing with the full model. If the merge is invalid, nothing is saved.

Python An update helper that validates the merge

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The second patch moves start past end. Each field is fine alone, but the merged trip fails the model validator, the endpoint answers 422, and the stored trip is untouched. Because apply_patch returns a new object instead of mutating the old one, a failed update can never leave half-applied changes behind.

With Pydantic you can shorten the merge for an existing model instance: current.model_copy(update=changes). It is quick, but it does not validate the changes, which is why the example above rebuilds the model with model_validate.

Idempotency

An operation is idempotent when doing it once or many times leaves the server in the same state. PUT and DELETE must be idempotent; so must GET. Sending the same PUT twice gives the same note. Clients, proxies and retry logic rely on that: if a network timeout hides the response, the client can safely resend a PUT.

PATCH is allowed to be non-idempotent: "increment views by one" is a legal patch, but resending it counts twice. If you stay with "set field to value" semantics, as in this lesson, your PATCH is idempotent too. POST (create) usually is not, which is why payment APIs add an idempotency key header.

Python Repeating requests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Three identical PUTs leave one state; three POSTs count three views.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A client sends PUT /notes/1 with a body that omits the optional field pinned (default False). What should happen?

    PUT represents the full new state, so omitted fields take their defaults.
  2. 2. Which call extracts only the fields the client actually sent in a PATCH body?

    exclude_unset drops fields that were never provided, while still keeping fields explicitly set to null.
  3. 3. Why validate the merged result of a patch with the full model?

    Cross-field rules only make sense on the complete object, so check the merged data before saving.
  4. 4. Which of these is idempotent?

    Setting a value gives the same state however often you repeat it. Creating or incrementing does not.

Summary

  • PUT replaces the whole resource; PATCH changes only the fields that were sent.
  • For PATCH, make every field optional and read the changes with model_dump(exclude_unset=True).
  • Never use exclude_none for PATCH: it can't distinguish "unchanged" from "set to null".
  • Merge changes into a copy and validate the full model before saving, so a bad update leaves nothing half-applied.
  • PUT and DELETE must be idempotent; "set to value" PATCHes are too.

Next: report problems clearly in status codes and error handling.