ESCUELA ESPECIALIZADA EN INGENIERIA ITCA-FEPADE MEGATEC LA UNION

ESCUELA DE INGENIERÍA EN COMPUTACIÓN

MÓDULO: UTILIZACIÓN DE FRAMEWORKS PARA EL DESARROLLO DE SOFTWARE

FACILITADOR: ING. EDGARDO A. CLAROS
ACTIVIDAD: GUÍA PRÁCTICA DE ELABORACIÓN DE API CON EL FRAMEWORK FASTAPI

INDICACIÓN: Siga los siguientes pasos detenidamente para desarrollar una API usando
el framework FastAPI de Python.
Una API REST (Representational State Transfer) es un estilo arquitectónico que sigue
ciertos principios para la comunicación entre el cliente y el servidor a través de HTTP.
Algunas de las características principales de las APIs REST son:

1. Sin estado: Cada solicitud que hace el cliente al servidor debe contener toda la
información necesaria para entender y procesar la solicitud. No se almacena el
estado del cliente en el servidor entre solicitudes.
2. Uso de métodos HTTP: Se utilizan los métodos HTTP estándar, como GET, POST,
PUT, DELETE, para realizar operaciones CRUD (Crear, Leer, Actualizar, Eliminar).
3. Recursos: Los recursos se identifican a través de URLs, y las operaciones sobre
esos recursos se realizan usando métodos HTTP.
4. Representaciones: Los recursos pueden representarse en varios formatos, como
JSON o XML. Generalmente, las APIs REST utilizan JSON como formato de
respuesta.

Características de la estructura mostrada que la hacen una API REST:

1. Rutas (endpoints) bien definidas: En la carpeta routers, puedes ver que las rutas
están organizadas, lo que permite acceder a los recursos (por ejemplo, /users/
para el recurso "usuarios").
o Ejemplo: Una ruta como @router.post("/users/") permite crear un nuevo
usuario en el sistema. Esto es típico de las APIs REST, donde cada recurso
tiene un endpoint y un verbo HTTP asociado (en este caso, POST).
2. Uso de verbos HTTP: Los métodos que definen la API usan los verbos HTTP estándar:
o GET para obtener recursos.
o POST para crear nuevos recursos.
o PUT/PATCH para actualizar recursos existentes.
o DELETE para eliminar recursos.

En el ejemplo que has visto, se está utilizando el método POST en el endpoint

/users/ para crear un usuario, lo cual sigue los principios REST.

3. Respuesta en formato JSON: En las APIs REST, los datos se intercambian

normalmente en formato JSON. En FastAPI, el uso de Pydantic en la carpeta
schemas facilita la serialización y
 deserialización de datos en formato JSON, que es la forma más común de
representar recursos en una API REST.
o En el ejemplo, la ruta devuelve un objeto UserOut, que es un esquema
Pydantic que se transformará en JSON para la respuesta.
4. Sin estado: Cada petición es independiente de las demás. Por ejemplo, cuando
haces una solicitud POST para crear un usuario, esa solicitud contiene toda la
información necesaria (como los datos del usuario) para que el servidor pueda
procesarla sin tener que depender del estado de solicitudes anteriores.

Hasta este punto hemos hablado de “endpoints”, sin embargo:

¿Qué es un endpoint?

En una API, un endpoint es una URL específica a la que un cliente (como un navegador o
una aplicación) puede hacer una solicitud para interactuar con los recursos del servidor.
Los endpoints definen las rutas que un cliente puede utilizar para realizar diferentes
operaciones, como obtener datos, crear nuevos registros, actualizar información o
eliminarla.

Cada endpoint en una API está asociado con un verbo HTTP y realiza una acción
específica sobre un recurso. Los verbos más comunes son:

 GET: Para obtener o leer recursos (datos).

 POST: Para crear un nuevo recurso.
 PUT o PATCH: Para actualizar un recurso existente.
 DELETE: Para eliminar un recurso.

Ejemplos de Endpoints:

1. GET /users: Obtiene la lista de todos los usuarios.

2. POST /users: Crea un nuevo usuario.
3. GET /users/{id}: Obtiene la información de un usuario específico con el identificador
id.
4. PUT /users/{id}: Actualiza la información de un usuario con el identificador id.
5. DELETE /users/{id}: Elimina un usuario con el identificador id.
¿Dónde se colocan los endpoints en una API?

En una API bien estructurada, los endpoints se suelen colocar en los archivos de rutas
(routers). Dependiendo del framework que estés usando, estos archivos pueden tener
diferentes nombres o ubicaciones, pero el concepto sigue siendo el mismo. En Python,
utilizando el framework FastAPI, los endpoints se definen en los archivos dentro de la
carpeta routers o routes, dependiendo de cómo organicemos un proyecto.

Conociendo la Estructura de una API

En una API estructurada, las carpetas models, routers, y schemas tienen un propósito
específico y juegan un rol importante en la organización del código, de las carpetas más
importantes son.

1. Carpeta models:

 Aquí es donde defines los modelos de tu aplicación. Los modelos suelen

representar las tablas en la base de datos cuando se utiliza un ORM (Object
Relational Mapper) como SQLAlchemy.
 En el caso de SQLAlchemy, en esta carpeta defines las clases que representan
cada tabla de tu base de datos. Cada clase es un modelo de datos que incluye
atributos correspondientes a las columnas de la tabla.

Ejemplo de un modelo en SQLAlchemy:

2. Carpeta models:

 Aquí se organizan los controladores de rutas de la API. Cada archivo o módulo en

esta carpeta suele contener rutas para un grupo de endpoints relacionados,
organizados lógicamente.
 FastAPI permite manejar las rutas usando routers, lo que facilita dividir las rutas
por funcionalidad o entidades. El siguiente es un ejemplo de un archivo de router:

3. Carpeta schemas:

 Aquí defines los esquemas que representan la validación y transformación de los

datos de entrada y salida de la API, normalmente usando Pydantic en FastAPI.
 Los esquemas son objetos que ayudan a validar los datos entrantes en las
solicitudes HTTP (POST, PUT, etc.) y también pueden definir cómo se devolverán
los datos en las respuestas.
Ejemplo de esquema en Pydantic:
Ejemplo de una Estructura Típica de una API

Propósito de Cada Directorio y Archivo:

1. pycache

 Este directorio es generado automáticamente por Python para almacenar archivos

bytecode compilados (.pyc), lo que ayuda a que la ejecución del programa sea más
rápida. No necesitas modificar nada en esta carpeta y generalmente se excluye en
los sistemas de control de versiones como Git.

2. Carpeta config

 Propósito: Aquí se almacenan archivos o configuraciones globales del proyecto,

como parámetros de conexión a la base de datos, configuraciones de variables de
entorno o parámetros específicos de la aplicación.
 Contenido típico: Archivos de configuración de la base de datos, configuraciones de
seguridad, etc.

3. Carpeta env

 Propósito: Esta carpeta puede estar relacionada con entornos virtuales o variables
de entorno. Es posible que contenga archivos de configuración o variables que se
usen dependiendo del ambiente (desarrollo, producción).
  Contenido típico: Variables de entorno o configuración del entorno virtual (.env),
que son útiles para manejar configuraciones sensibles como claves de API o
credenciales de base de datos.

4. Carpeta models

 Propósito: Aquí defines los modelos que representan las entidades de tu base de
datos. Estos modelos son clases que corresponden a tablas en la base de datos, y
suelen utilizarse con ORM como SQLAlchemy.
 Contenido típico: Clases que representan tablas de base de datos.

5. Carpeta routers

 Propósito: Aquí defines las rutas (endpoints) de la API. Esta carpeta organiza las
rutas en módulos, generalmente agrupados por funcionalidades o recursos (por
ejemplo, usuarios, productos, pedidos).
 Contenido típico: Archivos que manejan las rutas y la lógica de los endpoints.

6. Carpeta schemas

 Propósito: Aquí defines los esquemas que validan y estructuran los datos que
entran y salen de la API, normalmente utilizando Pydantic. Los esquemas ayudan a
validar los datos que reciben o envían los endpoints.
 Contenido típico: Clases de Pydantic que definen los datos que se aceptan o
devuelven en las rutas de la API.

7. main.py

 Propósito: Este archivo es el punto de entrada de la aplicación. Aquí se inicializa la

API, se conectan las rutas (routers) y se configuran los aspectos globales de la
aplicación.
 Contenido típico: Código que configura la API y ejecuta el servidor.
Resumen de la estructura

 pycache : Archivos generados automáticamente por Python.

 config: Configuraciones de la aplicación (ej. conexión a la base de datos).
 env: Variables de entorno para manejar configuraciones sensibles.
 models: Modelos de base de datos utilizando un ORM como SQLAlchemy.
 routers: Definiciones de las rutas (endpoints) y su lógica.
 schemas: Esquemas de validación de datos (entrantes y salientes) usando Pydantic.
 main.py: Punto de entrada de la aplicación, donde se configura la API y se
inicializan las rutas.

Este tipo de organización permite mantener un código más limpio, fácil de mantener y
escalable. Cada parte de la aplicación tiene su lugar bien definido, lo que facilita el
desarrollo y el trabajo en equipo.

Ahora Hablemos Sobre el Framework FastAPI

FastAPI es un framework web moderno y de alto rendimiento para construir APIs

(interfaces de programación de aplicaciones) en Python. Fue diseñado para que los
desarrolladores puedan crear APIs de manera rápida, eficiente y con un rendimiento
comparable al de frameworks como Node.js o Go. FastAPI es particularmente conocido
por ser fácil de usar, muy rápido y altamente compatible con las mejores prácticas de
desarrollo de APIs, como el uso de JSON, Pydantic para la validación de datos y OpenAPI
para la documentación automática.
Características principales de FastAPI:

1. Rendimiento muy alto:

o FastAPI está construido sobre Starlette (para el manejo de peticiones HTTP) y
Pydantic (para la validación de datos), y utiliza ASGI (Asynchronous Server
Gateway Interface), lo que permite manejar una gran cantidad de peticiones
concurrentes de forma eficiente. Su rendimiento es comparable con Node.js y
Go, y es más rápido que otros frameworks como Flask o Django.
2. Validación automática de datos:
o FastAPI utiliza Pydantic para validar los datos entrantes y salientes de
manera automática. Puedes definir esquemas de datos que deben cumplir
ciertos requisitos, y FastAPI se encargará de verificar que las peticiones
entrantes cumplan con esos requisitos sin que tengas que escribir código
adicional.
3. Asincronía (async/await):
o FastAPI soporta completamente el uso de async/await de Python, lo que
facilita el manejo de peticiones asíncronas. Esto es ideal para tareas que
pueden llevar tiempo, como consultas a bases de datos o llamadas a APIs
externas, sin bloquear el sistema.
4. Generación automática de documentación:
o FastAPI genera automáticamente una interfaz gráfica de la API utilizando
Swagger UI y Redoc. Esto significa que puedes ver y probar tu API
directamente desde el navegador sin necesidad de escribir documentación
manualmente.
o Basta con acceder a /docs o /redoc en tu servidor para obtener una interfaz
donde puedes interactuar con los diferentes endpoints.
5. Facilidad de uso:
o FastAPI está diseñado para que los desarrolladores puedan escribir menos
código y, al mismo tiempo, obtener características avanzadas. Su simplicidad
no compromete la potencia o la flexibilidad, lo que lo hace ideal tanto para
principiantes como para desarrolladores experimentados.
6. Basado en OpenAPI y JSON Schema:
o FastAPI sigue los estándares de OpenAPI (anteriormente conocido como
Swagger) para la creación de APIs y utiliza JSON Schema para la validación
de datos y generación de documentación. Esto asegura que la API esté bien
estructurada y documentada.
 7. Menor posibilidad de errores:
o Al usar tipos de datos con anotaciones en Python (type hints), FastAPI puede
validar tanto los tipos de entrada como de salida, reduciendo la cantidad de
errores que ocurren por valores inesperados o mal definidos.
8. Integración con bases de datos y OAuth2:
o FastAPI es compatible con una amplia variedad de bibliotecas, como
SQLAlchemy para trabajar con bases de datos, y ofrece soporte incorporado
para autenticación y autorización utilizando OAuth2.

Ventajas de usar FastAPI:

 Velocidad: FastAPI es uno de los frameworks más rápidos de Python gracias a su

arquitectura basada en ASGI.
 Facilidad de uso: La simplicidad y claridad en el código lo hacen ideal para
principiantes y equipos que necesitan ser productivos rápidamente.
 Validación y serialización automática: La validación y serialización de datos basada
en tipos simplifica mucho la programación y reduce errores.
 Documentación automática: El hecho de que FastAPI genere automáticamente una
documentación interactiva y fácil de usar es un gran plus para equipos que
necesitan entregar APIs a clientes externos.

¡Ahora que estamos listos, vamos a programar!

 DESARROLLO DE UNA API REST PARA UNA AGENCIA DE ALQUILERES DE VEHÍCULOS

 Lenguaje de programación: Python

 Framework: FastAPI
 SGBD: MySQL
 ORM: SQLAlchemy

NOTA: Su docente le proporcionará un script con la base de datos “bd_agencia”, es

importante que se asegure de generado en el servidor MySQL antes de comenzar a
programar la API.

Pasos Para el Desarrollo de la Api

1. Crear una carpeta en la raíz del disco con el nombre “api_agencia”

2. Abrir esa carpeta con Visual Studio Code

3. Crear un entorno virtual con el comando:

py -m venv env

4. Activar el entorno virtual con el comando:

env/Scripts/activate
 Si no permite la activación, debe iniciar una ventana de comando Porwer

Shell como administrador y ejecutar el siguiente comando: Set-

ExecutionPolicy RemoteSigned y luego confirmar la acción. Esto sucede

principalmente en sistemas Windows.

5. Instalar las herramientas para trabajar con FastAPI con el siguiente comando:

pip install fastapi uvicorn sqlalchemy pymysql

6. Crea la siguiente estructura de directorios y archivos en nuestro proyecto (ten

cuidado de no eliminar ni volver a crear los directorios que automáticamente ya

estarán creados como por ejemplo pycache , env, etc):

7. Código del archivo database.py (directorio: config)

En el archivo de conexión debes tener mucho cuidado con el puerto en el que está

configurado MySQL, en este caso es el 3306, sin embargo, debes asegurarte de ello en

tu servidor web.

8. Código del archivo models.py (directorio: models)

Observa que en este código debemos especificar la estructura de nuestras tablas en la

base de datos, detallando que campo es la clave primaria, los tipos de datos y

longitudes que se adapten a nuestro modelo en la tabla de la misma. Esta no es una

copia de las tablas, sino que es una representación de como se manejarán los modelos

de datos en nuestra API.

9. Código del archivo schemas.py (directorio: schemas)

Aquí defines los esquemas que representan la validación y transformación de los datos

de entrada y salida de la API, en otras palabras, Los esquemas son objetos que ayudan a

validar los datos entrantes en las solicitudes HTTP (POST, PUT, etc.) y también pueden

definir cómo se devolverán los datos en las respuestas.

10.Código del archivo clientes.py (directorio: routers)

NOTA: este código continúa en la siguiente página.

NOTA: Continuación del código anterior:

11.Código del archivo vendedores.py (directorio: routers)

NOTA: Continuación del código anterior:
12.Código del archivo main.py (directorio raíz)

13.Ahora probaremos ejecutar la API, por lo que abre una terminal en Visual Studio

Code y usa el siguiente comando:

uvicorn main:app --reload

Deberías visualizar algo como lo siguiente en tu terminal:

Esto significa que la API se está ejecutando satisfactoriamente en el localhost (http://127.0.0.1) y

está usando el puerto 8000

para probar su funcionamiento puedes abrir una ventana de un navegador web e introducir esta URL:
14.Probemos el funcionamiento de nuestra API, abre una ventana del navegador web e

introduce la siguiente dirección: http://127.0.0.1:8000

Deberías visualizar algo como lo siguiente:

15.Como siguiente paso haremos unas pruebas para acceder a la documentación de

la API, para ello ve a la siguiente dirección: http://127.0.0.1:8000/docs

Deberías visualizar algo como lo siguiente (esa es la documentación Swagger UI):

Si has llegado hasta este punto, lo que nos resta es probar el funcionamiento de todos
los endpoints de nuestra API, por lo que para ello podremos usar la documentación que
aparece en el paso anterior, o también podemos utilizar para este caso un programa
llamado Postman, con el cual tendrás una vista como la siguiente:

Para realizar estas pruebas, ya sea con la documentación propia de FastAPI (Swagger UI)
o por medio de Postman, deberás seguir los pasos que tu docente te orientará para
completar esas pruebas y validar que todo el funcionamiento sea el correcto en la API.

ACTIVIDAD DE TAREA

Siguiendo los pasos de la guía, realice las modificaciones necesarias para integrar los
módulos de marcas, proveedores y vehículos.

NOTA: investigue como validar los endpoints para agregar y eliminar registros de
manera que consideren la integridad referencian en la base de datos, tomando den
cuenta que si ocurre un error al insertar o eliminar la base de datos devuelve una
excepción. Esa validación debe aplicarla a los módulos que programará como tarea así
también a los de clientes y vendedores.

¡Suerte Coders!