Hoy traigo un pequeño HOWTO con una joya de Symfony. Se trata de un bundle, plugin o módulo (como prefieras llamarlo) para Symfony. Es una plataforma completa en origen, pero podemos sólo usar el núcleo de dicha plataforma en nuestro proyecto. Así en menos de 1 hora tendremos montada nuestra API en nuestro proyecto. Es decir, integrando el núcleo de este bundle en nuestro proyecto, se generarán automáticamente todas las funcionalidades clásicas de una API REST de todo lo que tengamos en nuestro proyecto.
Para los no duchos en el tema, una API es un punto de entrada a nuestro proyecto. Por ejemplo, si tenemos animales en nuestro proyecto, y dejamos en la API la gestión de estos animales, podremos listarlos, editarlos, crearlos o borrarlos.. Todo remotamente desde la API, desde una aplicación móvil, desde otra web, alimentando otros sistemas informáticos con esta información, cualquier cosa que se nos ocurra se puede hacer con una API.
Es decir, por excelencia las APIs son la mejor forma de interconectar sistemas informáticos. Y no es que ahora se hayan puesto de moda, sino que en el año 2000 se pusieron de moda. Y con Symfony mediante este proyecto se simplifica mucho su puesta en marcha.
El proyecto se llama API Platform, y su web es esta: https://api-platform.com/
Comenzando
Tenemos dos alternativas:
- Montar el proyecto completo de la API Platform, e incluir dentro de dicho proyecto, nuestra estructura de elementos de nuestro proyecto.
- O lo más sencillo, incluir el núcleo de la API Platform en nuestro proyecto. Si lo quieres rápido, y montarlo en menos de 1 hora, ésta es la forma.
Para la opción 2 necesitaremos un proyecto en Symfony estándar, actualizado a la última versión. A la fecha de hoy necesitaremos la versión 3.3 de Symfony por lo menos. Necesitaremos también tener los objetos de nuestro proyecto creados usando el ORM de Doctrine que viene incluido en Symfony de casa.
Cambios en nuestro proyecto
Lo primero es ejecutar desde línea de comandos, usando Composer, lo siguiente:
$ composer require api-platform/core
Esperamos a que se actualicen todas las librerías.. y vamos al núcleo de Symfony en donde incluimos el núcleo de la API en el fichero app/AppKernel.php:
$bundles = array( ... new ApiPlatform\Core\Bridge\Symfony\Bundle\ApiPlatformBundle(), ... );
Incluimos las rutas de la API en el fichero app/config/routing.yml así:
api:
resource: '.'
type: 'api_platform'
prefix: '/api' # Optional
Te recomiendo que pongas esto de arriba, al principio del fichero routing para evitar que entren otras rutas, y te aseguras de que todo lo que ataque a www.tusitio.com/api/ vaya a la API. Si quieres hacer llamadas de API personalizadas no tienes más que incluir tus rutas antes de las de arriba, en el fichero routing.yml de Symfony.
Quizá necesites algo como: www.tusitio.com/api/accion/personalizada/23 esto tendrás que ponerlo antes de las rutas incluidas para la API Platform, porque sino no te cargarán.
Sólo queda decirle a la API Platform los elementos que tiene disponibles. Entramos en nuestro directorio src/AppBundle/Entity/.. o donde tengamos nuestras entidades y les ponemos a cada una las siguientes dos líneas de código. Por ejemplo, en un objeto de tipo Animal quedaría tal que así:
use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\ORM\Mapping as ORM;
/**
* Animal.
*
* @ApiResource
* @ORM\Table(name="animal")
* @ORM\Entity(repositoryClass="AppBundle\Repository\AnimalRepository")
*/
class Animal
{
Ya está, seguimos poniendo estas dos líneas marcadas en negrita en todos los elementos de Doctrine y la API Platform las servirá automáticamente. Esto de nuevo es menos de 1 hora seguro 😉 vamos a ver cómo deben de verse los resultados..
Resultados
Si todo ha ido bien, y accedes al directorio /api mediante un navegador, tendrás un listado completo de todos los elementos en servicio y qué operaciones están permitidas. Con este proyecto de ejemplo se ve algo como la imagen de arriba, si desplegamos la primera acción (GET de animales) ves algo como esto. Incluso puedes probar las llamadas a la API haciendo listados, ediciones, creando nuevos elementos o borrándolos mediante la interfaz web que proporciona la API Platform. Es cojonudo, el listado de animales de este proyecto se ve así por ejemplo:
Ya tienes con esto una API completa sin apenas esfuerzo. ¡Un gran proyecto la API Platform!
Para terminar no me queda más que recomendar que pongas el directorio /api de tu proyecto bajo contraseña. Puedes montar un sistema de alta de usuarios de API, como si se tratara de cualquier otro directorio protegido con contraseña de Symfony. Ya de aquí en adelante cada uno tendrá que personalizarlo según las necesidades de su proyecto 🙂
