Request Body Validation

Validating incoming data is fundamental when building reliable APIs, especially those serving machine learning models. You need to ensure the data structure and types match what your model expects before attempting any processing or prediction. FastAPI makes this straightforward by integrating with Pydantic models.

When you define a path operation (like a POST or PUT request handler) that expects data in the request body, you can declare a function parameter with a type hint pointing to your Pydantic model. FastAPI uses this type hint to automatically handle request body validation.

Consider a scenario where your API endpoint needs to receive specific features for a prediction task. You can define a Pydantic model to represent the expected structure:

# main.py
from fastapi import FastAPI
from pydantic import BaseModel, Field
from typing import Optional # Use Optional or | None for optional fields

app = FastAPI()

class ModelInput(BaseModel):
    feature_alpha: float
    feature_beta: int = Field(gt=0, description="Beta feature must be positive")
    category: str
    optional_param: Optional[float] = None # Or use: float | None = None

@app.post("/process_data/")
async def process_data_endpoint(input_data: ModelInput):
    """
    Receives and processes data according to the ModelInput schema.
    """
    # If the code reaches here, input_data is guaranteed to be a valid
    # instance of ModelInput. FastAPI handled the validation.
    print(f"Received valid data: {input_data.dict()}")

    # Access validated data fields directly:
    result = input_data.feature_alpha * input_data.feature_beta

    # You can proceed with using this validated data, perhaps for ML inference
    return {"status": "success", "processed_result": result, "received_data": input_data}

In this example, the process_data_endpoint function expects a parameter named input_data with the type hint ModelInput. Here's what FastAPI automatically does when a request hits the /process_data/ endpoint with the POST method:

1. Reads the Request Body: FastAPI reads the raw bytes of the request body.
2. Parses JSON: It assumes the body contains JSON data and parses it into a Python dictionary.
3. Validates with Pydantic: It takes the parsed dictionary and attempts to create an instance of the ModelInput Pydantic model using this data. This step performs all the validation checks defined in the model:
   • Checks if required fields (feature_alpha, feature_beta, category) are present.
   • Checks if the data types match the annotations (float, int, str).
   • Applies any additional constraints (like gt=0 for feature_beta).
4. Injects Validated Data: If validation succeeds, FastAPI creates an instance of ModelInput populated with the request data and passes it as the input_data argument to your path operation function. Your function code can then safely use this object, knowing it conforms to the defined schema.
5. Handles Validation Errors: If parsing fails or the data does not conform to the ModelInput schema (e.g., a required field is missing, a type is incorrect, or a constraint like feature_beta > 0 is violated), FastAPI automatically stops processing the request. It generates and returns a JSON response with HTTP status code 422 Unprocessable Entity. This response includes detailed information about the validation errors, pinpointing exactly which fields were problematic and why.

Example: Valid Request

If you send a POST request to /process_data/ with the following JSON body:

{
  "feature_alpha": 10.5,
  "feature_beta": 5,
  "category": "A",
  "optional_param": 99.9
}

FastAPI will successfully validate this against the ModelInput model. Your process_data_endpoint function will execute, receiving a ModelInput instance, and the client will receive a 200 OK response similar to:

{
  "status": "success",
  "processed_result": 52.5,
  "received_data": {
    "feature_alpha": 10.5,
    "feature_beta": 5,
    "category": "A",
    "optional_param": 99.9
  }
}

Example: Invalid Request

Now, consider sending a POST request with an invalid body:

{
  "feature_alpha": "not-a-float",
  "category": "B"
}

This payload is invalid for two reasons: feature_alpha is a string instead of a float, and the required feature_beta field is missing. FastAPI automatically catches these errors and returns a 422 Unprocessable Entity response like this:

{
  "detail": [
    {
      "loc": [
        "body",
        "feature_alpha"
      ],
      "msg": "value is not a valid float",
      "type": "type_error.float"
    },
    {
      "loc": [
        "body",
        "feature_beta"
      ],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Notice how the error response clearly indicates the location (loc) and reason (msg, type) for each validation failure within the request body. This immediate and detailed feedback is invaluable for API clients during development and debugging.

By simply using Pydantic models as type hints for your request body parameters, you gain automatic, declarative data validation with clear error reporting, significantly reducing boilerplate code and improving the reliability of your API endpoints. This ensures that the data reaching your application logic, and potentially your machine learning models, is structured and typed correctly. Furthermore, FastAPI uses these Pydantic models to automatically generate schemas for your API documentation (like Swagger UI), making your API self-documenting regarding expected request formats.