response-model

16 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Response model via return type annotation

Declare the response type by annotating the path operation function return type. FastAPI will validate the returned data, add JSON Schema for OpenAPI documentation, serialize the data to JSON using Pydantic, and limit and filter output data to what is defined in the return type.

response_model decorator parameter for non-matching return types

Use the response_model parameter in path operation decorators (@app.get(), @app.post(), @app.put(), @app.delete(), etc.) when you need to return a type that differs from the declared response type. This allows you to return a dictionary or database object while declaring it as a Pydantic model for documentation and validation. The response_model parameter receives the same type you would declare for a Pydantic model field, including lists of models like List[Item].

response_model takes priority over return type annotation

If you declare both a return type and a response_model, the response_model will take priority and be used by FastAPI. This allows you to add correct type annotations for your editor and tools like mypy while having FastAPI perform data validation and filtering using the response_model.

Disable response model with response_model=None

Set response_model=None to disable creating a response model for a path operation. This is needed when adding type annotations for things that are not valid Pydantic fields, allowing you to have any return type annotations without affecting FastAPI's application.

Use class inheritance for type hints and data filtering

Create a base model with common fields, then have input and output models inherit from it. Annotate the function return type as the base class while actually returning a subclass instance. This provides editor and mypy support while allowing FastAPI to filter data based on the return type annotation, not class inheritance.

Return Response directly without response model

When you return a Response class or subclass (such as RedirectResponse or JSONResponse) directly, FastAPI automatically handles this and skips response model generation. Tools recognize this as valid because subclasses of Response are correct type annotations.

response_model_exclude_unset parameter

Set response_model_exclude_unset=True in the path operation decorator to omit fields with default values from the response if they were not explicitly set. Only values actually set will be included in the response.

response_model_exclude_defaults and response_model_exclude_none parameters

Use response_model_exclude_defaults=True to exclude fields that have default values, and response_model_exclude_none=True to exclude fields with None values, as described in the Pydantic documentation for serialization.

Explicitly set fields included despite matching defaults

When using response_model_exclude_unset=True, fields that are explicitly set to their default values will still be included in the response. Pydantic recognizes when a field was set explicitly versus taken from defaults.

response_model_include and response_model_exclude parameters

Use response_model_include to specify a set of attribute names to include (omitting the rest), or response_model_exclude to specify attribute names to exclude (including the rest). Both take a set of strings with attribute names. These work as quick shortcuts if you have only one Pydantic model and want to remove some data from output, but using multiple classes is still recommended.

response_model_include and response_model_exclude JSON Schema limitation

The JSON Schema generated in OpenAPI documentation will still represent the complete model even if response_model_include or response_model_exclude are used to omit attributes from actual responses. This also applies to response_model_by_alias.

Use lists or tuples instead of sets for response_model_include/exclude

If you use a list or tuple instead of a set for response_model_include or response_model_exclude, FastAPI will automatically convert it to a set and it will work correctly.

response_model_by_alias parameter

response_model_by_alias works similarly to response_model_include and response_model_exclude, affecting which fields are included in the response.

Security consideration: separate input and output models for password fields

Never store or send a user's plain password in a response. Create separate input and output models where the input model (e.g., UserIn) includes the password field and the output model (e.g., UserOut) excludes it. Use response_model to ensure FastAPI filters out sensitive data.

HeroPublic - model for API responses

Create a HeroPublic data model that is returned to the clients of the API. This model excludes sensitive fields like secret_name. It re-declares id as int (not None) to make a contract with API clients that they can always expect the id to be there and to be an int.

response_model parameter with different return type

Use response_model parameter instead of return type annotation when the value being returned is a different type than the response model. FastAPI will use the response_model to validate and serialize the data without interfering with type annotations.

Give your agent this brain