¿Cómo se comunica FastAPI con REST?

Al observar incluso una aplicación mínima de FastAPI, el clásico ejemplo de "Hello World", es posible empezar a analizar cómo FastAPI estructura los puntos finales (endpoints). En este contexto, un punto final especifica los siguientes detalles:

• Una combinación única de URL: Esta será la misma en tu servidor de desarrollo — localhost:8000.

• Un path: La parte que sigue después de la barra (/).

• Un método HTTP.

En una nueva carpeta llamada "Chapter4", por ejemplo, crea un archivo Python llamado chapter4_01.py utilizando Visual Studio Code:

python
Copy code
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
    return {"message": "Hello FastAPI"}

Con este código, se pueden lograr varias cosas. Aquí tienes un desglose de lo que hace cada parte:

• En la primera línea de chapter4_01.py, se importa la clase FastAPI del paquete fastapi.

• Luego, se instancia un objeto de la aplicación. Este es solo una clase de Python con todas las funcionalidades de la API, que expone una aplicación compatible con ASGI, la cual debe ser pasada a Uvicorn. Ahora, la aplicación está lista e instanciada. Pero sin puntos finales, no puede hacer mucho o decir nada.

• Tiene un solo punto final, el root, que puedes ver en http://127.0.0.1:8000/. FastAPI expone decoradores para métodos HTTP para indicarle a la aplicación cómo y si debe responder. Sin embargo, debes implementarlos. Luego, se utiliza el decorador @get, que corresponde al método GET, y se pasa una URL; en este caso, se usa el path raíz (/).

• La función decorada, llamada root, es responsable de responder a las solicitudes. Acepta cualquier argumento (en este caso, no hay ninguno). El valor devuelto por la función, típicamente un diccionario de Python, se transformará en una respuesta en formato JSON por el servidor ASGI y será retornada como una respuesta HTTP.

Esto puede parecer obvio, pero es útil desglosarlo para entender los fundamentos. El código anterior define una aplicación completamente funcional con un solo punto final. Para probarla, necesitas un servidor Uvicorn. Ahora, debes ejecutar el servidor en vivo con Uvicorn desde la línea de comandos:

bash
Copy code
uvicorn chapter4_01:app --reload

Este fragmento de código lo utilizarás con frecuencia al desarrollar con FastAPI. A continuación, desglosamos cómo funciona:

Nota
Uvicorn es tu servidor web compatible con ASGI. Puedes llamarlo directamente pasando la combinación del archivo Python ejecutable (sin la extensión) y la aplicación instanciada (FastAPI), separados por dos puntos (:). La opción --reload le indica a Uvicorn que recargue el servidor cada vez que guardes tu código, algo similar a Nodemon en Node.js. A menos que se indique lo contrario, puedes ejecutar todos los ejemplos de este libro que contienen aplicaciones FastAPI utilizando esta sintaxis.

A continuación, el resultado al probar tu único punto final con HTTPie. Recuerda que cuando omites la palabra clave para el método, por defecto se usa una solicitud GET:

bash
Copy code
(venv) http http://localhost:8000/
HTTP/1.1 200 OK
content-length: 27
content-type: application/json
date: Fri, 01 Apr 2022 17:35:48 GMT
server: uvicorn
{
  "message": "Hello FastAPI"
}

HTTPie te informa que tu punto final simple está funcionando. Obtendrás un código de estado 200 OK, el tipo de contenido está correctamente establecido como application/json, y la respuesta es un objeto JSON que contiene el mensaje deseado.

python
Copy code
@app.post("/")
async def post_root():
    return {"message": "¡Solicitud POST exitosa!"}

HTTPie responderá de manera acorde en la terminal:

bash
Copy code
(venv) http POST http://localhost:8000

HTTP/1.1 200 OK
content-length: 35
content-type: application/json
date: Sat, 26 Mar 2022 12:49:25 GMT
server: uvicorn
{
  "message": "¡Solicitud POST exitosa!"
}

Ahora que has creado un par de puntos finales, dirígete a http://localhost:8000/docs y observa lo que FastAPI ha generado para ti. Esta es una característica que distingue a FastAPI. La documentación automática e interactiva facilita el desarrollo de APIs REST. Con cada punto final o enrutador que desarrolles, FastAPI genera automáticamente una documentación interactiva. Esta documentación permite probar la API a medida que la desarrollas. Muestra todos los puntos finales definidos y proporciona información sobre las entradas y salidas esperadas. La documentación está basada en la especificación OpenAPI y hace uso extensivo de las sugerencias de Python y la biblioteca Pydantic. Permite configurar los datos JSON o de formulario que se enviarán a los puntos finales, muestra respuestas o errores, está estrechamente vinculada con Pydantic y es capaz de manejar procedimientos de autorización simples, como el flujo del token Bearer que se implementará en el capítulo 6, sobre Autenticación y Autorización.

Una vez que hayas creado una API mínima, pero completamente funcional, con un solo punto final, comprenderás mejor la sintaxis y la estructura de la aplicación. En la siguiente sección, aprenderás sobre los elementos básicos del ciclo de solicitud-respuesta de una API REST y cómo puedes controlar cada aspecto del proceso.

Importante: Además de comprender los aspectos básicos de los puntos finales en FastAPI, es crucial saber cómo manejar diferentes tipos de solicitudes, cómo configurar encabezados y parámetros dinámicos y cómo estructurar tus respuestas para cumplir con los estándares de una API RESTful. FastAPI se distingue por su capacidad de generar documentación en vivo y su integración sencilla con herramientas como Pydantic para la validación y serialización de datos.

¿Cómo implementar una API con operaciones CRUD para gestionar coches?

En primer lugar, se debe entender cómo construir un endpoint GET que devuelva una lista de coches. Este tipo de consulta es fundamental en cualquier API que gestione una colección de elementos. Para facilitar su implementación, se utiliza un GET que permite obtener todos los coches de la base de datos, aunque con la posibilidad de limitar el número de resultados enviados al cliente.

python
Copy code
@router.get("/", response_description="List all cars")

async def list_cars(request: Request):
    cars = request.app.db["cars"]
    result = await cars.find().to_list(1000)  # Limita el número de resultados
    return result

Este fragmento de código representa cómo obtener todos los coches disponibles en la base de datos. Es importante tener en cuenta que se debe gestionar el volumen de datos. Si la colección crece, se hace necesario implementar un sistema de paginación que divida los resultados en múltiples páginas. En lugar de devolver todos los registros a la vez, lo que podría sobrecargar al cliente, se limita la respuesta a un número determinado de registros por página.

Sin embargo, es igual de importante ofrecer una forma de obtener un solo coche a partir de su ID. En este caso, se usa un GET donde el ID del coche es pasado como parámetro de la ruta, y se devuelve el coche si existe.

python
Copy code
@router.get("/{id}", response_description="Get a single car by ID", response_model=CarModel)

async def show_car(id: str, request: Request):
    cars = request.app.db["cars"]
    try:
        id = ObjectId(id)
    except Exception:

        raise HTTPException(status_code=404, detail=f"Car {id} not found")

    car = await cars.find_one({"_id": id})
    if car:
        return car
    raise HTTPException(status_code=404, detail=f"Car with {id} not found")

Ahora bien, es fundamental que cualquier API también permita modificar registros existentes. Para lograr esto, se utiliza un PUT para actualizar un coche. Este método verifica qué campos han sido modificados en el objeto y los actualiza en la base de datos.

python
Copy code
@router.put("/{id}", response_description="Update a car")

async def update_car(id: str, request: Request, car: UpdateCarModel = Body(...)):
    cars = request.app.db["cars"]
    try:
        id = ObjectId(id)
    except Exception:
        raise HTTPException(status_code=404, detail=f"Car {id} not found")
    update_result = await cars.find_one_and_update(

        {"_id": ObjectId(id)}, {"$set": car.dict(exclude_unset=True)}

    )
    if update_result:
        return update_result
    raise HTTPException(status_code=404, detail=f"Car {id} not found")

Finalmente, es necesario contar con un endpoint DELETE para eliminar registros. Este es un método sencillo donde se elimina el coche cuyo ID coincide con el proporcionado:

python
Copy code
@router.delete("/{id}", response_description="Delete a car")

async def delete_car(id: str, request: Request):

    cars = request.app.db["cars"]
    delete_result = await cars.delete_one({"_id": ObjectId(id)})
    if delete_result.deleted_count == 1:
        return Response(status_code=status.HTTP_204_NO_CONTENT)
    raise HTTPException(status_code=404, detail=f"Car {id} not found")

Este endpoint elimina el coche de la base de datos si existe, y devuelve un estado 204 No Content para indicar que la operación fue exitosa pero no requiere respuesta adicional.

A medida que se gestionan más coches, una de las mejores prácticas es implementar paginación de resultados para evitar sobrecargar al usuario con demasiados datos a la vez. En lugar de devolver todos los coches de la base de datos en una sola consulta, se puede dividir la respuesta en "páginas". La paginación se puede gestionar utilizando parámetros como page y limit, que indican qué página de resultados debe mostrarse y cuántos coches por página se deben devolver.

python
Copy code
@router.get("/", response_description="List all cars, paginated", response_model=CarCollectionPagination)

async def list_cars(request: Request, page: int = 1, limit: int = 10):
    cars = request.app.db["cars"]
    cursor = cars.find().limit(limit).skip((page - 1) * limit)
    total_documents = await cars.count_documents({})
    has_more = total_documents > page * limit
    results = []
    async for document in cursor:
        results.append(document)
    return CarCollectionPagination(cars=results, page=page, has_more=has_more)

Este código permite dividir la colección de coches en varias páginas, facilitando la carga y visualización de los resultados en la interfaz de usuario.

Es esencial que el cliente de la API pueda manejar la paginación correctamente, visualizando el número total de páginas y el estado de si hay más resultados disponibles. Al retornar el campo has_more, podemos informar al usuario si debe esperar más resultados en páginas posteriores. También se pueden incluir enlaces o botones para navegar entre las páginas, lo que mejora la experiencia del usuario en interfaces de usuario más complejas.

Es importante que el lector comprenda que, al trabajar con bases de datos como MongoDB, la paginación y las consultas eficientes son clave para el rendimiento de la aplicación. La implementación de una API que maneje cientos o miles de registros sin una estrategia adecuada de paginación puede resultar en tiempos de respuesta lentos y una mala experiencia para el usuario.