Validar lo que un usuario envía a tu API es la diferencia entre un endpoint frágil y uno confiable. Con Pydantic en FastAPI puedes definir modelos de datos que validan automáticamente cada campo del request body, sin escribir métodos manuales de validación. Esta guía te muestra cómo crear tu primer modelo Customer y conectarlo a un endpoint POST.

¿Por qué usar Pydantic para validar el body de un request?

Cuando aceptas información dentro del body, el usuario puede mandar cualquier cosa: un correo mal escrito, un número donde esperabas texto o campos vacíos. Sin validación, esos datos llegan sucios a tu lógica de negocio.

Pydantic resuelve eso con clases que representan un modelo de datos. Tú declaras los tipos de cada campo y la librería se encarga de revisar el contenido entrante. Si algo no cumple, FastAPI devuelve un error claro al frontend para mostrarle al usuario qué corregir [1:00].

¿Qué es Pydantic? Es un módulo de Python que crea clases para modelar y validar datos. FastAPI lo usa por defecto para revisar lo que entra en cada endpoint.

¿Cómo creo un modelo Customer con BaseModel?

El punto de partida es importar BaseModel desde Pydantic, que se instala junto con FastAPI. Luego defines una clase que herede de ese BaseModel y añades los campos con su tipo [1:45].

Pydantic se apoya en el typing de Python: si declaras un campo como str, valida que llegue un string; si lo declaras como int, exige un número entero.

python from pydantic import BaseModel

class Customer(BaseModel): name: str description: str | None email: str age: int

¿Para qué sirve el operador str pipe none?

El operador | (pipe) indica que un campo puede ser de varios tipos. En el caso de description: str | None, le estás diciendo a Pydantic que la descripción puede ser un texto o estar vacía [2:50].

Esto es útil cuando un campo es opcional: si el cliente se crea solo con nombre, no quieres mostrar un error por falta de descripción. Para el campo email, por ahora se valida como str, aunque lo ideal es usar un tipo email dedicado más adelante.

¿Cómo conecto el modelo a un endpoint POST en FastAPI?

Una vez listo el modelo, lo usas como tipo del parámetro que recibe el endpoint. FastAPI detecta que es un BaseModel y automáticamente lo lee desde el body del request [3:55].

python @app.post("/customers") async def create_customer(customer_data: Customer): return customer_data

Fíjate en dos detalles importantes:

• El path usa plural (/customers), una convención recomendada al diseñar APIs REST.
• El método correcto para crear recursos es POST, no GET. GET sirve para leer; POST, para crear [4:40].

Dentro de create_customer puedes ejecutar la lógica que necesites: guardar en base de datos, enviar notificaciones o disparar un correo. En el ejemplo simplemente se retorna el mismo objeto recibido para verificar que la validación funciona.

¿Cuándo debo usar POST en vez de GET? Usa POST cuando creas un recurso nuevo y envías datos en el body. GET es para consultar información sin modificar nada en el servidor.

¿Qué códigos de respuesta devuelve FastAPI al validar?

Al probar el endpoint desde la documentación automática (/docs), FastAPI muestra los campos requeridos, un ejemplo del JSON y un botón Try it out para enviar peticiones reales [5:30].

Cuando mandas datos válidos, como name: Luis Martínez, email: hola@lcmartinez.com y age: 33, el servidor responde con código 200. Sin embargo, al crear recursos lo correcto es devolver 201, que indica creación exitosa. Mientras no guardes en base de datos, FastAPI deja el 200 por defecto [6:45].

¿Qué pasa si envío un tipo de dato incorrecto?

Si en name mandas un número como 123124 en lugar de un string, FastAPI no ejecuta el endpoint: responde con un 422 Validation Error y un mensaje que apunta a la ubicación exacta del problema, por ejemplo body.name, indicando que el input debe ser un string válido [7:30].

Ese mensaje es oro para el frontend: te dice qué campo falló y por qué, así puedes mostrarle al usuario un error puntual en su formulario.

Recursos clave que aparecen en el flujo

• BaseModel: clase base de Pydantic de la que heredan todos tus modelos para activar la validación automática.
• Typing de Python: anotaciones como str, int o str | None que Pydantic interpreta para validar.
• Decorador @app.post: registra el endpoint bajo el método HTTP correcto para crear recursos.
• Documentación automática en /docs: interfaz generada por FastAPI donde pruebas tus endpoints sin necesidad de Postman ni curl.
• Uvicorn: servidor ASGI que ejecuta tu aplicación cuando corres fastapi dev.

¿Qué otros campos validarías en tu modelo Customer y cómo manejarías el caso del email? Cuéntame en los comentarios cómo estás estructurando tus propios modelos.