Todo lo que necesitas saber sobre los parámetros de consulta en FastAPI (con las mejores prácticas)

FastAPI es un framework web moderno de alto rendimiento para construir APIs con Python. Una de sus características más destacadas es el manejo de parámetros de consulta de FastAPI, que permite a los desarrolladores crear APIs flexibles y fáciles de usar. En este artículo, exploraremos las mejores prácticas y técnicas para usar los parámetros de consulta de FastAPI de manera efectiva en 2024.

¿Por qué usar los parámetros de consulta de FastAPI?

Flexibilidad: Los parámetros de consulta de FastAPI permiten a los clientes personalizar los resultados de sus solicitudes. Por ejemplo, los usuarios pueden filtrar los resultados de búsqueda según criterios específicos como categoría, precio o calificación.
Usabilidad: Simplifican la interacción entre los clientes y la API. Los clientes pueden agregar fácilmente parámetros de consulta a la URL, mientras que los desarrolladores pueden validar y procesar rápidamente estos parámetros en su código.
Rendimiento: Al usar los parámetros de consulta de FastAPI, puedes reducir el número de endpoints requeridos para una API. En lugar de crear endpoints separados para cada opción de filtrado, un solo endpoint puede manejar múltiples parámetros de consulta.

Cómo usar los parámetros de consulta de FastAPI

Definición de los parámetros de consulta de FastAPI

Para definir parámetros de consulta en FastAPI, simplemente inclúyelos como parámetros de función en la definición de tu endpoint. Aquí tienes un ejemplo básico:

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
    q: str | None = Query(default=None, max_length=50),
    skip: int = Query(default=0, ge=0),
    limit: int = Query(default=10, le=100)
):
    return {"q": q, "skip": skip, "limit": limit}

En este ejemplo:

q: Un parámetro de cadena opcional con una longitud máxima de 50 caracteres.
skip: Un parámetro entero que especifica cuántos elementos omitir, con un valor predeterminado de 0 y un valor mínimo de 0.
limit: Un parámetro entero que especifica el número máximo de elementos a devolver, con un valor predeterminado de 10 y un valor máximo de 100.

Acceso a los parámetros de consulta de FastAPI

Cuando un cliente realiza una solicitud al endpoint, FastAPI extrae automáticamente los parámetros de consulta de la URL y los pasa a la función. Por ejemplo, si se realiza una solicitud a /items/?q=foo&skip=10&limit=5, la función recibirá:

q = "foo"
skip = 10
limit = 5

Esta extracción automática facilita el trabajo con los parámetros de consulta de FastAPI sin lógica de análisis adicional.

Parámetros de consulta de FastAPI opcionales y obligatorios

De forma predeterminada, los parámetros de consulta de FastAPI son opcionales. Si no se proporciona un parámetro en la solicitud, FastAPI utilizará el valor predeterminado especificado. Para que un parámetro de consulta sea obligatorio, simplemente omite el valor predeterminado:

@app.get("/items/")
async def read_items(required_param: str):
    return {"required_param": required_param}

Si el required_param no se incluye en la solicitud, FastAPI devolverá un error 422 Unprocessable Entity, indicando que falta un parámetro de consulta obligatorio.

Manejo de múltiples valores para los parámetros de consulta de FastAPI

FastAPI te permite definir un parámetro de consulta que puede aceptar múltiples valores. Puedes hacer esto especificando el tipo de parámetro como una lista:

from typing import List

@app.get("/items/")
async def read_items(q: List[str] = Query(default=[])):
    return {"q": q}

En este caso, el cliente puede hacer una solicitud como /items/?q=foo&q=bar&q=baz, y FastAPI analizará los valores en una lista. Esta característica es particularmente útil para escenarios donde los usuarios quieren filtrar los resultados basándose en múltiples criterios.

💡

¿Buscas mejorar tu desarrollo de API? Prueba Apidog. Esta poderosa herramienta es perfecta para mejorar tus proyectos de FastAPI y más. Pruébala gratis y mira cómo puede optimizar tu flujo de trabajo y aumentar la eficiencia

button

Validación de los parámetros de consulta de FastAPI

FastAPI proporciona validación incorporada para los parámetros de consulta utilizando la función Query. Puedes especificar restricciones como valores mínimos y máximos, restricciones de longitud y patrones regex. Aquí tienes un ejemplo:

@app.get("/items/")
async def read_items(
    q: str = Query(default=None, min_length=3, max_length=50),
    item_id: int = Query(ge=1, le=100)
):
    return {"q": q, "item_id": item_id}

En este ejemplo, q debe ser una cadena con una longitud mínima de 3 y una longitud máxima de 50. El item_id debe ser un entero entre 1 y 100. FastAPI validará automáticamente estas restricciones y devolverá un error si la entrada no cumple con los criterios especificados.

Generación automática de documentación con FastAPI y OpenAPI

Una de las ventajas destacadas de usar FastAPI es su perfecta integración con OpenAPI, que permite la generación automática de documentación interactiva de la API. Esta característica mejora la usabilidad de tu API y proporciona una mejor experiencia para los desarrolladores que consumen tu API. Aquí tienes una mirada más cercana a cómo FastAPI logra esto y cómo puedes mejorar la documentación para tus parámetros de consulta.

¿Qué es OpenAPI?

OpenAPI es una especificación para construir APIs que proporciona una forma estándar de describir las capacidades de tu API. Permite tanto a humanos como a máquinas entender las capacidades de un servicio sin acceder a su código fuente o ver ninguna documentación adicional. FastAPI aprovecha esta especificación para generar automáticamente documentación interactiva para tus endpoints de API.

Cómo FastAPI genera la documentación

Cuando defines tu aplicación FastAPI y sus endpoints, FastAPI crea automáticamente un esquema OpenAPI basado en las firmas de función y los tipos de los parámetros que defines. Este esquema incluye:

Rutas de endpoint: Las rutas que defines en tu aplicación.
Métodos HTTP: Los métodos (GET, POST, PUT, DELETE, etc.) asociados con cada endpoint.
Parámetros: Tanto los parámetros de ruta como los de consulta, incluyendo sus tipos, valores predeterminados y restricciones.
Modelos de respuesta: El formato de respuesta esperado para cada endpoint.

Cómo documentar interactivamente con FastAPI

FastAPI proporciona dos interfaces de documentación interactiva listas para usar:

Swagger UI: Accesible en /docs, esta interfaz permite a los usuarios explorar los endpoints de tu API, ver los formatos de solicitud y respuesta, e incluso probar los endpoints directamente desde el navegador.
ReDoc: Disponible en /redoc, esta interfaz proporciona una vista más detallada y estructurada de la documentación de tu API, facilitando la navegación y la comprensión de los diversos endpoints y sus parámetros.

Ambas interfaces se generan automáticamente basándose en el esquema OpenAPI creado por FastAPI, asegurando que tu documentación esté siempre actualizada con tu código.

Mejora de la documentación para los parámetros de consulta

Si bien FastAPI genera documentación básica para tus parámetros de consulta, puedes mejorarla aún más proporcionando descripciones detalladas, ejemplos y metadatos adicionales. Aquí te mostramos cómo:

Texto descriptivo: Utiliza el parámetro description en la función Query para proporcionar explicaciones claras de lo que hace cada parámetro de consulta. Esto es particularmente útil para los usuarios que pueden no estar familiarizados con tu API.

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
    q: str | None = Query(default=None, description="Término de búsqueda para filtrar elementos."),
    skip: int = Query(default=0, ge=0, description="Número de elementos a omitir."),
    limit: int = Query(default=10, le=100, description="Número máximo de elementos a devolver.")
):
    return {"q": q, "skip": skip, "limit": limit}

2. Ejemplos: Proporciona ejemplos para tus parámetros de consulta para ilustrar cómo se pueden usar. Esto es particularmente útil para parámetros complejos o cuando hay formatos específicos que deben seguirse.

@app.get("/items/")
async def read_items(
    q: str | None = Query(default=None, description="Término de búsqueda para filtrar elementos.", example="manzana"),
    skip: int = Query(default=0, ge=0, description="Número de elementos a omitir.", example=5),
    limit: int = Query(default=10, le=100, description="Número máximo de elementos a devolver.", example=20)
):
    return {"q": q, "skip": skip, "limit": limit}

3. Restricciones de validación: Indica claramente cualquier restricción de validación para tus parámetros de consulta. Esto incluye valores mínimos y máximos, restricciones de longitud y cualquier formato específico. FastAPI maneja estas validaciones automáticamente, pero documentarlas ayuda a los usuarios a comprender los límites.

4. Anotaciones de tipo: Utiliza anotaciones de tipo apropiadas para tus parámetros de consulta. FastAPI utiliza estas anotaciones para generar automáticamente los tipos de datos esperados en la documentación, lo que ayuda a los usuarios a comprender qué tipo de datos deben proporcionar.

5. Agrupación de parámetros relacionados: Si tu API tiene varios parámetros de consulta relacionados, considera agruparlos lógicamente. Esto puede ayudar a los usuarios a comprender cómo interactúan los parámetros entre sí y qué combinaciones son válidas.

Beneficios de la documentación mejorada

Usabilidad mejorada: Los parámetros de consulta bien documentados facilitan a los desarrolladores la comprensión de cómo interactuar con tu API. Esto reduce la curva de aprendizaje y aumenta la adopción.
Solicitudes de soporte reducidas: Una documentación clara puede ayudar a responder preguntas comunes y reducir el número de solicitudes de soporte que recibes de los usuarios que intentan comprender cómo usar tu API.
Desarrollo más rápido: Los desarrolladores pueden consultar rápidamente la documentación mientras construyen aplicaciones, lo que lleva a ciclos de integración y desarrollo más rápidos.
Mayor adopción de la API: Una documentación completa y fácil de usar puede atraer a más desarrolladores para que utilicen tu API, mejorando su éxito y alcance general.
Consistencia: La documentación automática asegura que la documentación de tu API sea consistente con la implementación real, reduciendo las discrepancias que pueden llevar a la confusión.

Técnicas avanzadas para los parámetros de consulta de FastAPI

Uso de Enums para los parámetros de consulta de FastAPI

Puedes restringir los parámetros de consulta de FastAPI a un conjunto predefinido de valores utilizando Enums de Python. Esto es útil para los parámetros que solo deben aceptar opciones específicas:

from enum import Enum

class ItemType(str, Enum):
    fruit = "fruit"
    vegetable = "vegetable"
    dairy = "dairy"

@app.get("/items/")
async def read_items(item_type: ItemType):
    return {"item_type": item_type}

En este ejemplo, el parámetro de consulta item_type solo puede ser uno de los valores definidos en el Enum ItemType. Si el cliente proporciona un valor no válido, FastAPI devolverá un error 422.

Dependencias de los parámetros de consulta

FastAPI te permite crear dependencias para los parámetros de consulta, lo que puede ayudarte a reutilizar la lógica en múltiples endpoints. Puedes definir una función de dependencia que devuelve un valor basado en los parámetros de consulta:

from fastapi import Depends

def query_param_dependency(q: str | None = None):
    return q if q else "default"

@app.get("/items/")
async def read_items(q: str = Depends(query_param_dependency)):
    return {"q": q}

En este ejemplo, la función query_param_dependency comprueba si se proporciona el parámetro de consulta q. Si no, devuelve un valor predeterminado. Este enfoque promueve la reutilización del código y mantiene limpias las funciones de tu endpoint.

Manejo de errores para los parámetros de consulta de FastAPI

FastAPI maneja automáticamente los errores relacionados con los parámetros de consulta. Si falta un parámetro de consulta obligatorio o si un parámetro falla la validación, FastAPI devuelve una respuesta 422 Unprocessable Entity con un mensaje de error detallado. Puedes personalizar el manejo de errores utilizando manejadores de excepciones:

from fastapi import HTTPException

@app.get("/items/")
async def read_items(q: str | None = Query(default=None)):
    if q is None:
        raise HTTPException(status_code=400, detail="El parámetro de consulta 'q' es obligatorio.")
    return {"q": q}

Este ejemplo demuestra cómo generar una excepción HTTP personalizada cuando no se proporciona un parámetro de consulta obligatorio. Este enfoque te permite proporcionar mensajes de error más informativos a los clientes.

Prueba de los parámetros de consulta de FastAPI

Probar tu aplicación FastAPI es crucial para asegurar que tus parámetros de consulta funcionen como se espera. Puedes utilizar la biblioteca httpx para realizar pruebas en tus endpoints de FastAPI. Aquí tienes un ejemplo:

import httpx
import pytest

@pytest.mark.asyncio
async def test_read_items():
    async with httpx.AsyncClient() as client:
        response = await client.get("http://localhost:8000/items/?q=test&skip=0&limit=10")
        assert response.status_code == 200
        assert response.json() == {"q": "test", "skip": 0, "limit": 10}

En esta prueba, hacemos una solicitud GET al endpoint /items/ con parámetros de consulta y afirmamos que la respuesta es la esperada. La prueba es una parte esencial del proceso de desarrollo, asegurando que tu API se comporte correctamente al manejar los parámetros de consulta de FastAPI.

Conclusión

Los parámetros de consulta de FastAPI son una característica poderosa que te permite pasar datos adicionales a tus endpoints de API a través de la URL. Proporcionan flexibilidad, usabilidad y beneficios de rendimiento al construir APIs con FastAPI. En esta guía, exploramos cómo definir, acceder, validar y documentar los parámetros de consulta de FastAPI utilizando ejemplos detallados. Cubrimos temas como parámetros opcionales y obligatorios, múltiples valores, tipos complejos y generación automática de documentación. También discutimos técnicas avanzadas, manejo de errores, pruebas y errores comunes. Al aprovechar los parámetros de consulta de FastAPI, puedes crear APIs más flexibles y fáciles de usar que pueden manejar varios requisitos de filtrado, ordenación y paginación sin la necesidad de múltiples endpoints dedicados. Recuerda elegir los tipos de parámetros, validaciones y descripciones apropiados para asegurar que tu API sea fácil de usar y esté bien documentada para tus clientes. Las poderosas capacidades de los parámetros de consulta de FastAPI pueden mejorar significativamente la funcionalidad y usabilidad de tu API, convirtiéndola en una excelente opción para las aplicaciones web modernas.

Recursos adicionales sobre FastAPI

Para mejorar aún más tu comprensión de los parámetros de consulta de FastAPI, considera explorar los siguientes recursos:

Documentación de FastAPI: La documentación oficial de FastAPI proporciona información completa sobre los parámetros de consulta y otras características.
Repositorio de FastAPI en GitHub: Consulta el repositorio de FastAPI en GitHub para obtener código fuente, ejemplos y contribuciones de la comunidad.
Tutoriales de FastAPI: Busca tutoriales y cursos en línea que se centren en FastAPI para profundizar tus conocimientos y habilidades.

Siguiendo estas mejores prácticas y técnicas para los parámetros de consulta de FastAPI, puedes construir APIs robustas y eficientes que satisfagan las necesidades de tus usuarios en 2024 y más allá.

button