Skip to main content

Understanding response model

FastAPI allows you to leverage Python's type annotations to define your API's input and output data structures. This feature makes it easier to develop, test, and maintain your API. One essential concept in FastAPI is the 'Response Model', which refers to the data structure of the responses that your API returns.

What is a Response Model?​

A Response Model in FastAPI is a Python data class that defines the structure of the data that your API endpoint returns. It leverages the Pydantic library, which FastAPI uses for data validation and serialization. A response model is a Pydantic model.

Here's an example of a simple response model:

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str
    price: float

In this example, Item is a response model that defines an item with a name, description, and price.

How to Use a Response Model?​

You can declare a response model for an API endpoint by specifying it as the response_model parameter in FastAPI's route operation decorator.

Here's an example:

from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str
    price: float

app = FastAPI()

@app.get("/items/{item_id}", response_model=Item)
async def read_item(item_id: int):
    return {"name": "Foo", "description": "A very nice Item", "price": 42.0}

In this example, FastAPI will automatically convert the returned dict into the Item model and use it to generate the response.

Benefits of Using a Response Model​

  1. Output Data Shaping: The response model allows you to control the shape of the output data, ensuring that it conforms to the defined structure.

  2. Data Validation: Response models validate the output data. If the data doesn't conform to the model, FastAPI will raise an error.

  3. Automatic API Documentation: FastAPI uses response models to generate interactive API documentation automatically.

  4. Serialization: FastAPI uses Pydantic's serialization to convert output data to JSON format.

Customizing Response Model​

FastAPI allows you to customize the response model to fit your needs. You can specify which fields to include, exclude, and more.

Here's an example:

from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str
    price: float
    tax: float = 10.5

app = FastAPI()

@app.get("/items/{item_id}", response_model=Item, response_model_exclude={"tax"})
async def read_item(item_id: int):
    return {"name": "Foo", "description": "A very nice Item", "price": 42.0, "tax": 7.0}

In the above example, FastAPI will exclude the tax field from the response.

This was a brief overview of response models in FastAPI. They are a powerful tool for ensuring your API's data integrity, shaping the output data, and generating API documentation. Use them wisely to create robust and maintainable APIs.