Desarrollo de una API REST para gestión de productos y valoraciones con FastAPI y MySQL

Una API REST (Representational State Transfer) es un tipo de API que sigue los principios de la arquitectura REST. REST es un estilo de arquitectura que utiliza HTTP para realizar operaciones CRUD (Create, Read, Update, Delete) en recursos. En nuestro caso, los recursos normalmente serán tablas de una base de datos. Las APIs RESTful son diseñadas para ser simples, escalables y eficientes, utilizando métodos HTTP estándar y formatos de intercambio de datos como JSON y XML.

La principal diferencia entre una API y una API REST es que las APIs RESTful siguen los principios de la arquitectura REST, mientras que otras APIs pueden no seguir estos principios. Las APIs RESTful utilizan métodos HTTP estándar (GET, POST, PUT, DELETE) para realizar operaciones en recursos y utilizan URLs para identificar recursos específicos.

La figura siguiente ilustra las peticiones a una API RESTful utilizando los métodos HTTP estándar GET, POST, PUT y DELETE. Estas peticiones son enviadas a través de URLs que identifican los recursos específicos. Al ser recibidas por la API RESTful, se procesan (interactuando con la base de datos) y se envían las respuestas correspondientes.

Los métodos HTTP son utilizados para realizar operaciones en recursos en una API RESTful. Los métodos más comunes y sus principales usos son:

Cada uno de estos métodos tiene un propósito específico y se utiliza en diferentes situaciones para interactuar con los recursos de una API. Desde el punto de vista de bases de datos, cada uno lo podríamos hacer corresponder con una operación básica de SQL CRUD:

Los formatos de intercambio de datos son utilizados para representar la información que se envía y recibe a través de una API. Los dos formatos más comunes son JSON (JavaScript Object Notation) y XML (eXtensible Markup Language).

Los endpoints de una API son las URLs a las que se envían las solicitudes para interactuar con los recursos de la API. Cada endpoint representa una operación específica que se puede realizar en un recurso. Como ejemplos de endpoints, se pueden mencionar:

A continuación se explican algunos aspectos importantes sobre cómo especificar los endpoints de una API.

Las cabeceras HTTP son utilizadas para proporcionar información adicional sobre la solicitud o la respuesta. Algunas de las cabeceras más comunes son:

Las cabeceras son importantes para asegurar que la solicitud y la respuesta sean interpretadas correctamente por el cliente y el servidor.

Docker Compose es una herramienta que permite definir y ejecutar aplicaciones Docker con múltiples contenedores. Con Docker Compose, se puede configurar el entorno de desarrollo de la API REST definiendo los servicios necesarios en un archivo docker-compose.yml. Este archivo especifica cómo se deben construir y ejecutar los contenedores de Docker para la aplicación, incluyendo las dependencias entre los servicios, los volúmenes para persistencia de datos y el mapeo de puertos para acceder a los servicios desde el host. Comencemos con un archivo docker-compose.yml básico, que por ahora define únicamente los servicios de MySQL y Python para la API REST. Este archivo lo situaremos en una carpeta denominada setup-environment que se encuentra en la raíz del proyecto y se utiliza para configurar y ejecutar los contenedores de Docker necesarios para la aplicación.

Se utiliza un archivo .env para definir las variables de entorno necesarias para la configuración de MySQL. Este archivo lo situamos en la misma carpeta setup-environment que el archivo docker-compose.yml. A continuación se muestra un ejemplo del contenido del archivo .env con las variables de entorno necesarias para configurar MySQL:

Este entorno inicial de desarrollo incluye dos servicios:

Usaremos un archivo Dockerfile para construir el contenedor de Python con las dependencias necesarias para ejecutar la API REST. A continuación se muestra el contenido del archivo Dockerfile:

Como archivo de requisitos, se utiliza requirements.txt para instalar las dependencias necesarias para la API REST. A continuación se muestra el contenido del archivo requirements.txt:

FastAPI es un framework moderno y de alto rendimiento para construir una APIs REST utilizando Python. Está diseñado para ser fácil de usar, rápido y eficiente, aprovechando las características más recientes de Python, como las anotaciones de tipo (type hints). Algunas de sus características principales incluyen:

Swagger y ReDoc son herramientas de documentación de APIs que permiten visualizar y probar las rutas de la API de forma interactiva. FastAPI genera automáticamente documentación interactiva para las APIs en formato Swagger y ReDoc. La documentación se genera automáticamente a partir de las anotaciones de tipo y los esquemas definidos en el código. Los esquemas de datos se utilizan para validar las entradas y salidas de las rutas de la API y los definiremos utilizando Pydantic. Pydantic es una biblioteca de validación de datos y serialización de objetos que se integra perfectamente con FastAPI.

La documentación Swagger generada está disponible en la ruta /docs de la aplicación FastAPI. Es posible cambiar el título y la descripción de la documentación de Swagger utilizando los parámetros title y description al crear la aplicación FastAPI. Esto lo veremos más adelante cuando comencemos con el desarrollo.

Por otro lado, ReDoc es otra herramienta de documentación que presenta las rutas de la API de manera más estructurada y profesional. Está disponible en la ruta /redoc.

Ambas herramientas son generadas automáticamente por FastAPI a partir de las anotaciones de tipo y los esquemas definidos en el código. Esto elimina la necesidad de escribir documentación manualmente y asegura que siempre esté sincronizada con la implementación de la API.

Para mantener el código organizado y facilitar el desarrollo, se recomienda dividir la aplicación en módulos y archivos separados. En FastAPI, se pueden definir las rutas y la lógica de negocio en módulos separados, y luego importarlos en el archivo principal de la aplicación. Esto facilita la gestión de rutas y la escalabilidad de la aplicación. A continuación se muestra una propuesta de organización de código en FastAPI.

Para comenzar nuestra API desde cero, crearemos un archivo main.py con el siguiente código. Este archivo es el punto de entrada de la aplicación FastAPI y define la aplicación y una ruta de prueba para verificar que la API está funcionando correctamente. Por ahora, este archivo sólo contiene la definición de la aplicación FastAPI con una descripción personalizada.

Antes de pasar a la implementación de la lógica de negocio y la interacción con la base de datos, vamos a crear algunas rutas básicas de prueba para asegurarnos de que la API REST está funcionando correctamente. Estas rutas se pueden utilizar para verificar que el servidor está respondiendo a las solicitudes y que la configuración inicial es correcta.

Organizaremos todas nuestras rutas en archivos separados dentro de una carpeta routers para mantener el código organizado. Para comenzar, crearemos un archivo routers/base.py con el siguiente código, que define una ruta de prueba para verificar que la API REST está funcionando correctamente.

Luego, en el archivo main.py, importamos el router definido en routers/base.py y lo incluimos en la aplicación FastAPI para que la ruta de prueba esté disponible. A continuación se muestra el código actualizado del archivo main.py con la inclusión del router:

Si ejecutamos el entorno de desarrollo con Docker Compose y accedemos a http://localhost:8000/health, deberíamos recibir una respuesta JSON con el estado de la API REST, indicando que está funcionando correctamente. Esto confirma que la configuración inicial del entorno de desarrollo es correcta y que la API REST está respondiendo a las solicitudes.

HATEOAS (Hypermedia as the Engine of Application State) es un principio de diseño de APIs REST que sugiere que las respuestas de la API no deben incluir sólo datos, sino también enlaces a otros recursos relacionados, lo que permite a los clientes navegar por la API de manera dinámica y descubrir nuevas funcionalidades sin necesidad de conocer previamente la estructura de la API. En este tutorial, se realizará una implementación muy básica de HATEOAS en la API REST para proporcionar enlaces a recursos relacionados en las respuestas de la API. Esto mejorará la experiencia del usuario al permitir una navegación más intuitiva y facilitará la exploración de la API sin necesidad de consultar la documentación para conocer las rutas disponibles.

Para ello, definiremos en la ruta raíz (/) un endpoint que devuelva un mensaje de bienvenida junto con enlaces a los recursos principales de la API REST. Más adelante, a medida que implementemos los endpoints para gestionar usuarios, productos, categorías y valoraciones, también incluiremos enlaces a recursos relacionados en las respuestas de esos endpoints para seguir el principio de HATEOAS. Esto permitirá a los clientes descubrir fácilmente cómo interactuar con la API REST y navegar por los diferentes recursos disponibles. A continuación se muestra un ejemplo de cómo implementar mínimamente HATEOAS en la ruta raíz de la API REST:

En la respuesta de esta ruta raíz, se incluye un mensaje de bienvenida y un diccionario _links que contiene enlaces a recursos relacionados, como:

Esto permite a los clientes descubrir fácilmente cómo interactuar con la API REST y navegar por los diferentes recursos disponibles sin necesidad de consultar la documentación para conocer las rutas disponibles. Así se mostraría la respuesta JSON al acceder a la ruta raíz (/):

Ahora podemos ir navegando por la API REST utilizando los enlaces proporcionados en la respuesta de la ruta raíz, lo que facilita la exploración de la API y mejora la experiencia del usuario al interactuar con la API REST. Por ejemplo, al hacer clic sobre el enlace de Swagger (/docs), se accederá a la documentación interactiva de la API REST, donde se pueden probar los diferentes endpoints y ver cómo funcionan. De esta manera, se sigue el principio de HATEOAS al proporcionar enlaces a recursos relacionados en las respuestas de la API REST, lo que permite a los clientes navegar por la API de manera dinámica y descubrir nuevas funcionalidades sin necesidad de conocer previamente la estructura de la API.

Igualmente, al hacer clic sobre el enlace de Redoc (/redoc), se accederá a otra versión de la documentación de la API REST con un formato diferente, lo que ofrece a los usuarios una experiencia de navegación más rica y variada.

Esto demuestra cómo la implementación de HATEOAS en la API REST mejora la experiencia del usuario al permitir una navegación más intuitiva y facilitar la exploración de la API sin necesidad de consultar la documentación para conocer las rutas disponibles.

Para conectar la API REST a la base de datos MySQL, se puede utilizar el conector de MySQL para Python. Esto permite interactuar con la base de datos MySQL directamente desde el código Python. Sin embargo, para mejorar el rendimiento y la eficiencia en la gestión de conexiones a la base de datos, es recomendable utilizar un pool de conexiones. A continuación se muestra un ejemplo de cómo configurar la conexión a MySQL utilizando un pool de conexiones. Este código se puede colocar en un archivo database.py que se encargue de gestionar la conexión a MySQL y proporcionar una función para obtener una conexión desde el pool.

El ejemplo que vamos a usar a lo largo del tutorial es una base de datos para gestionar productos y valoraciones en un entorno de comercio electrónico. Los productos se organizan en categorías, y los usuarios pueden dejar valoraciones y comentarios sobre los productos. La figura siguiente muestra en formato PlantUML el esquema de la base de datos que vamos a utilizar para almacenar los datos de usuarios, productos, categorías y valoraciones.

A continuación se muestra el código para crear las tablas users, categories, products y reviews en la base de datos MySQL utilizando sentencias SQL. Colocaremos este código en un archivo 'init_db.py' que se encargue de la inicialización de la base de datos. Este código se ejecutará al inicio de la aplicación para asegurarse de que las tablas necesarias estén creadas en la base de datos antes de que se realicen operaciones sobre ellas.

Ahora, ya sólo queda ejecutar la función create_tables al inicio de la aplicación para asegurarnos de que las tablas necesarias estén creadas en la base de datos antes de que se realicen operaciones sobre ellas. Para ello, podemos importar la función create_tables en el archivo main.py y llamarla al inicio de la aplicación. A continuación se muestra el código actualizado del archivo main.py con la llamada a la función create_tables:

Si ahora lanzamos una petición a la raíz de la API REST en http://localhost:8000, se ejecutará el código de inicialización de la base de datos y se crearán las tablas users, categories, products y reviews si no existen. Esto asegura que la base de datos esté preparada para almacenar los datos de usuarios, productos, categorías y valoraciones que se gestionarán a través de la API REST. Una vez lanzada esta petición, podemos abrir una sesión en MySQL o utilizar una herramienta como MySQL Workbench para verificar que las tablas se han creado correctamente en la base de datos. Usaremos las credenciales definidas en el archivo .env para conectarnos a la base de datos MySQL y verificar que las tablas users, categories, products y reviews han sido creadas correctamente. Al abrir la conexión a la base de datos, deberíamos ver estas tablas listadas en el esquema de la base de datos, lo que confirma que la inicialización de la base de datos se ha realizado correctamente.

Los endpoints representan las rutas a las que los clientes pueden enviar solicitudes para interactuar con la API REST. A continuación se muestra una descripción de los endpoints disponibles en la API REST para gestionar usuarios, productos, categorías y valoraciones:

Los modelos de datos representan la estructura de los datos que se manejan en la API REST. Esto es, los modelos de datos definen cómo se representan los usuarios, productos, categorías y valoraciones en la API REST. Esto es importante para validar los datos de entrada y salida de las rutas de la API, asegurando que los datos cumplen con la estructura esperada y facilitando la generación automática de documentación a través de Swagger. En FastAPI, se utiliza Pydantic, una biblioteca de validación de datos que permite definir modelos de datos utilizando clases de Python. FastAPI utiliza estas clases Pydantic para definir los modelos de datos, lo que permite validar automáticamente los datos de entrada y salida de las rutas de la API. Por ejemplo, el modelo Product se utiliza para validar los datos de un producto y el modelo ProductResponse se utiliza para devolver los datos de un producto con su ID. Para definir las clases usaremos la especificación de los JSON que se ha hecho en la sección Especificación de los endpoints de la API. Definiremos también clases de respuesta para los modelos de datos, que incluyen el ID generado por la base de datos.

Para crear los endpoints de usuarios, deberemos hacer estas tareas:

Los endpoints para productos, categorías y valoraciones se implementarán de manera similar a los endpoints de usuarios, siguiendo la misma estructura y lógica para manejar las operaciones CRUD (Crear, Leer, Actualizar, Eliminar) en cada recurso. Se crearán archivos de router específicos para cada recurso (por ejemplo, routers/products.py, routers/categories.py, routers/reviews.py) y se añadirán al enrutado principal en main.py con los prefijos y etiquetas correspondientes. Cada endpoint se encargará de validar los datos de entrada utilizando los modelos Pydantic definidos en models.py, ejecutar las operaciones SQL necesarias para interactuar con la base de datos MySQL y devolver las respuestas adecuadas según el resultado de cada operación.

Además de los endpoints básicos para gestionar usuarios, productos, categorías y valoraciones, se pueden incorporar funcionalidades adicionales para mejorar la experiencia del usuario y la eficiencia de la API REST. Algunas de estas funcionalidades podrían incluir:

Tras implementar el resto de endpoints de la API, actualizamos la implementación de HATEOAS para incluir enlaces a los nuevos endpoints de productos, categorías y valoraciones. Esto permitirá a los clientes descubrir fácilmente las operaciones disponibles en la API REST y navegar por los recursos relacionados de manera intuitiva. Nos limitaremos a poder acceder a los usuarios, catetorías, productos y valoraciones desde el endpoint raíz.

Si ahora queremos poder navegar de forma completa, podemos añadir enlaces HATEOAS adicionales en cada endpoint para permitir a los clientes descubrir fácilmente las operaciones relacionadas con cada recurso. Por ejemplo, en el endpoint GET /products, podríamos incluir enlaces a los endpoints de detalle de producto, actualización y eliminación para cada producto devuelto en la lista. Esto permitiría a los clientes navegar de manera intuitiva entre los recursos relacionados y realizar operaciones adicionales sobre los productos sin tener que conocer previamente la estructura de la API REST.

Definir los índices adecuados en MySQL es una práctica esencial para optimizar el rendimiento de las consultas y garantizar que la API funcione de manera eficiente, incluso con grandes volúmenes de datos. Para mejorar el rendimiento de los endpoints, es recomendable definir los siguientes índices en MySQL: