🐾 Proyecto Registro de Animales#

Imagen de un gato usando la computadora

✨ Descripción General

El proyecto Registro de Animales es un ejemplo práctico de cómo crear un API REST utilizando Python y FastAPI. Incluye un backend, un frontend y pruebas automatizadas para gestionar un registro de animales.

📋 Descripción general del funcionamiento del backend y el frontend#

El backend está construido con FastAPI. Los archivos de implementación se encuentran en la ruta /app/proyectos/asantelis. Ahí se definen cinco operaciones principales:

📜 Obtener lista de animales registrados
➕ Registrar un nuevo animal
🔍 Obtener detalles de un animal específico
✏️ Actualizar información de un animal
🗑️ Eliminar un registro de animal

El frontend está construido con React y Astro. Se conecta al backend mediante la url http://127.0.0.1:8000/api/v1/asantelis/animales.

🔄 Carga inicial de datos#

Cuando el usuario arranca el programa de frontend, este se conecta al backend para obtener la lista de animales registrados.

A continuación se muestra un diagrama de secuencia que muestra la comunicación inicial entre el frontend y el backend, justo después de que el usuario accedió al frontend.

sequenceDiagram
    participant Usuario
    participant Frontend
    participant Backend


    Usuario-->>Frontend: Arranca frontend de Registro de Animales
    Note over Usuario, Backend: Carga inicial de datos
    rect rgb(191, 123, 155)
        activate Frontend
            Frontend->>Backend: GET /api/v1/asantelis/animales
            activate Backend
            Backend-->>Frontend: Retorna la lista de animales registrados
            deactivate Backend
            Note right of Frontend: Actualiza la tabla de animales
            Frontend-->>Usuario: Muestra la lista de animales
        deactivate Frontend
    end

➕ Registro de un nuevo animal#

Una vez que el usuario ha arrancado el frontend y los datos iniciales han sido cargados, el usuario puede registrar un nuevo animal mediante el formulario de registro. Cuando el usuario completa el formulario y hace clic en el botón "Agregar", el frontend realiza una petición al backend para registrar el nuevo animal.

Captura de pantalla del formulario de registro

El formulario tiene validaciones básicas para no permitir campos vacíos, edades negativas, etc. Además del mensaje de error, el botón "Agregar" no se habilitará hasta que el usuario haya completado correctamente todos los campos requeridos.

Si el usuario introdujo datos válidos y presiona el botón "Agregar", el frontend hará la operación de registro con el backend. Si la transacción se acepta, volverá a contactar al backend para descargar la lista actualizada de animales y actualizar la interfaz con la nueva información. Ver el siguiente diagrama de secuencia.

sequenceDiagram
    participant Usuario
    participant Frontend
    participant Backend

    Note over Usuario, Backend: Proceso de registro de animal
    rect rgb(91, 23, 155)
    Usuario->>Frontend: Completa formulario y hace clic en "Agregar"
    Frontend->>Backend: POST /api/v1/asantelis/animales
    Backend-->>Frontend: Transacción exitosa (201 Created)
    Frontend->>Backend: GET /api/v1/asantelis/animales
    Backend-->>Frontend: Retorna la lista actualizada de animales
    Note right of Frontend: Actualiza la tabla de animales
    Frontend-->>Usuario: Muestra mensaje de éxito y lista actualizada
    end

Finalmente, la aplicación de frontend luce así después de varios registros.

Captura de pantalla despues de varios registros

✏️ Actualización de información de un animal#

Otra operación importante es la actualización de la información de un animal registrado. El usuario puede hacer clic en el botón "Editar" junto al animal que desea modificar, lo que cargará los datos actuales en el formulario. Después de realizar los cambios necesarios, el usuario puede hacer clic en "Actualizar" para guardar los cambios.

sequenceDiagram
    participant Usuario
    participant Frontend
    participant Backend

    Note over Usuario, Backend: Proceso de actualización de animal
    rect rgb(91, 123, 55)
    Usuario->>Frontend: Hace clic en "Editar" junto a un animal
    Note right of Frontend: Carga datos actuales en el formulario
    Frontend-->>Usuario: Muestra formulario con datos actuales
    Usuario->>Frontend: Modifica datos y hace clic en "Actualizar"
    Frontend->>Backend: PUT /api/v1/asantelis/animales/{id}
    Backend-->>Frontend: Transacción exitosa (200 OK)
    Frontend->>Backend: GET /api/v1/asantelis/animales
    Backend-->>Frontend: Retorna la lista actualizada de animales
    Note right of Frontend: Actualiza la tabla de animales
    Frontend-->>Usuario: Muestra mensaje de éxito y lista actualizada
    end

🗑️ Eliminación de un animal#

La última operación principal es la eliminación de un registro de animal. El usuario puede hacer clic en el botón "Eliminar" junto al animal que desea eliminar, lo que mostrará un diálogo de confirmación. Si el usuario confirma la eliminación, el frontend realizará una petición al backend para eliminar el registro.

sequenceDiagram
    participant Usuario
    participant Frontend
    participant Backend

    Note over Usuario, Backend: Proceso de eliminación de animal
    rect rgb(191, 23, 55)
    Usuario->>Frontend: Hace clic en "Eliminar" junto a un animal
    Note right of Frontend: Muestra diálogo de confirmación
    Frontend-->>Usuario: Solicita confirmación
    Usuario->>Frontend: Confirma eliminación
    Frontend->>Backend: DELETE /api/v1/asantelis/animales/{id}
    Backend-->>Frontend: Transacción exitosa (204 No Content)
    Frontend->>Backend: GET /api/v1/asantelis/animales
    Backend-->>Frontend: Retorna la lista actualizada de animales
    Note right of Frontend: Actualiza la tabla de animales
    Frontend-->>Usuario: Muestra mensaje de éxito y lista actualizada
    end

🖥️ Backend - Detalle#

El código fuente del backend se encuentra en el módulo app/proyectos/asantelis. Está desarrollado utilizando FastAPI y expone cinco rutas:

GET /animales: Obtiene la lista de todos los animales registrados. Link a la función
POST /animales: Registra un nuevo animal. Link a la función
GET /animales/{animal_id}: Obtiene los detalles de un animal específico. Link a la función
PUT /animales/{animal_id}: Actualiza la información de un animal específico. Link a la función
DELETE /animales/{animal_id}: Elimina el registro de un animal específico. Link a la función

A continuación se muestran los links a la documentación de cada submódulo.

Documentación de rutas Documentación de modelos Documentación de esquemas

🚀 Cómo arrancar el backend#

Para iniciar el backend, utiliza el siguiente comando:

uv run fastapi run

🧪 Pruebas del Backend#

Las pruebas automatizadas del backend se encuentran en el archivo /tests/test_asantelis.py. Estas pruebas verifican el correcto funcionamiento de las rutas y la lógica de negocio, incluyendo:

🗃️ Comportamiento de la API cuando la base de datos está vacía
🐾 Creación de registros de animales
✏️ Actualización de registros de animales
🗑️ Eliminación de registros de animales
🔍 Validación de datos de entrada para registros de animales

Documentación de funciones de prueba

🧪 Cómo ejecutar las pruebas#

Para ejecutar las pruebas, utiliza el siguiente comando:

uv run pytest

🎨 Frontend#

El código fuente del frontend se encuentra en el directorio /frontend/asantelis/app/. Este frontend interactúa con el backend para mostrar la lista de animales registrados y permitir operaciones como registro, actualización y eliminación.

Documentación de Funciones del frontend

🚀 Cómo arrancar el frontend#

Para iniciar el frontend, primero asegúrate de que el backend esté en ejecución, luego abre otra terminal, navega al directorio del frontend y utiliza los siguientes comandos:

cd frontend/asantelis/app
npm install
npm run dev

Después, abre tu navegador en la dirección que se muestra en la terminal (generalmente http://localhost:4321).