TDW: REST API - Anales de la Ciencia

🎯Implementación de una API REST para la gestión aportaciones a la Ciencia

Este proyecto implementa una interfaz de programación REST desarrollada sobre el framework Slim. La aplicación proporcionará las operaciones habituales para la gestión de Productos, Entidades y Personas.

Para hacer más sencilla la gestión de los datos se ha utilizado el ORM Doctrine. Doctrine 2 es un Object-Relational Mapper que proporciona persistencia transparente para objetos PHP. Utiliza el patrón Data Mapper con el objetivo de obtener un desacoplamiento completo entre la lógica de negocio y la persistencia de los datos en los sistemas de gestión de bases de datos.

Para su configuración, este proyecto se apoya en el componente Dotenv, que permite realizar la configuración a través de variables de entorno. De esta manera, cualquier configuración que pueda variar entre diferentes entornos (desarrollo, pre-producción, producción, ...) puede ser establecida a través de variables de entorno, tal como se aconseja en la metodología “The twelve-factor app” ✔️.

Por otra parte se incluye parcialmente la especificación de la API (OpenAPI 3.0). Esta especificación se ha elaborado empleando el editor Swagger. Adicionalmente también se incluye la interfaz de usuario (SwaggerUI) de esta fenomenal herramienta que permite realizar pruebas interactivas de manera completa y elegante. La especificación entregada define las operaciones sobre usuarios del sistema y Productos, por lo que queda por implementar las operaciones relativas a la gestión de Entidades y Personas.

⚙Instalación del proyecto️

El primer paso consiste en generar un esquema de base de datos vacío y un usuario/contraseña con privilegios completos sobre dicho esquema.

Después se deberá crear una copia del fichero ./.env y renombrarla como ./.env.local. Después se debe editar dicho fichero y modificar las variables DATABASE_NAME, DATABASE_USER y DATABASE_PASSWD con los valores generados en el paso anterior (el resto de opciones pueden quedar como comentarios). Una vez editado el anterior fichero y desde el directorio raíz del proyecto se deben ejecutar los comandos:

> composer update
> bin/doctrine orm:schema:update --dump-sql --force

Para verificar la validez de la información de mapeo y la sincronización con la base de datos:

> bin/doctrine orm:validate

🗄️Estructura del proyecto

A continuación se describe el contenido y estructura más destacado del proyecto:

• Directorio bin:
  • Ejecutables (doctrine, phpunit, ...)
• Directorio config:
  • config/cli-config.php: configuración de la consola de comandos de Doctrine, configuración de la aplicación, asociación entre rutas y controladores, etc.
• Directorio src:
  • Subdirectorio src/Entity: entidades PHP (incluyen anotaciones de mapeo del ORM)
  • Subdirectorio src/Controller: controladores PHP (implementan los endpoints de la API)
  • Subdirectorio src/scripts: scripts de ejemplo
• Directorio public:
  • Raíz de documentos del servidor web
  • public/index.php: controlador frontal
  • public/api-docs: especificación de la API (Swagger-UI)
  • public/demoAjax: ejemplo básico acceso a la API (login)
• Directorio tests:
  • Pruebas unitarias y funcionales de la API
• Directorio vendor:
  • Componentes desarrollados por terceros (Doctrine, DotENV, Slim, etc.)

🚀Puesta en marcha de la aplicación

Para acceder a la aplicación utilizando el servidor interno del intérprete de PHP se ejecutará el comando:

> php -S 127.0.0.1:8000 -t public

Una vez hecho esto, la aplicación estará disponible en http://127.0.0.1:8000/.

🛠️Ejecución de pruebas

La aplicación incorpora un conjunto completo de herramientas para la ejecución de pruebas unitarias y de integración con PHPUnit. Empleando este conjunto de herramientas es posible comprobar de manera automática el correcto funcionamiento de la API completa sin la necesidad de herramientas adicionales.

Para configurar el entorno de pruebas se debe crear un nuevo esquema de bases de datos vacío, y una copia del fichero ./phpunit.xml.dist y renombrarla como ./phpunit.xml. Después se debe editar este último fichero para asignar los siguientes parámetros:

• Configuración (líneas 15-17) del acceso a la nueva base de datos (DATABASE_NAME, DATABASE_USER y DATABASE_PASSWD)
• Si se desea (líneas 21-23), se pueden modificar el nombre y contraseña de los usuarios que se van a emplear para realizar las pruebas (no es necesario insertarlos, lo hace automáticamente el método setUpBeforeClass() de la clase BaseTestCase)

Para lanzar la suite de pruebas completa se debe ejecutar:

> bin/phpunit [--testdox] [--coverage-text] [-v]

Adicionalmente, para comprobar la calidad de las pruebas, el proyecto incluye test de mutaciones generados con la herramienta Infection. El funcionamiento es simple: se generan pequeños cambios en el código original (mutantes), y a continuación se ejecuta la batería de pruebas. Si las pruebas fallan, indica que han sido capaces de detectar la modificación del código, y el mutante es eliminado. Si pasa las pruebas, el mutante sobrevive y la fiabilidad de la prueba queda cuestionada.

Para lanzar los test de mutaciones se ejecutará:

> composer infection