Creando una API Restful con la API Platform desde cero

Aquí llega otro sencillo codekata o howto para crear una API Restful en PHP, from scratch, en pocos minutos, sobre Mysql o Mariadb, y usando esta joya del software llamada API Platform.

A esta API se le puede conectar cualquier otro software como una aplicación en React, Angular, WordPress, Magento.. aplicaciones hechas en varios lenguajes como Java, Python, PHP, JavaScript, etcétera. Estas APIs son una forma de conectar sistemas de forma totalmente estándar.

Este post es continuación de este sobre crear APIs a partir de proyectos funcionales, o complemento de este otro sobre cómo filtrar elementos en la API Platform. También se complementa con este post posterior sobre PHP y una clase estándar para consulta de APIs.

Punto de partida

En el punto de partida necesitamos un servidor con una base de datos compatible con Mysql. Suponemos que también tenemos instalado PHP, Composer y las nociones básicas de Symfony.

Si no es así te invito a instalarte todo, revisar los temas básicos sobre Symfony, y volver a este punto.. ?

Qué es una API, una API Rest, y una API Restful

Por definición una API es una Interfaz de programación de aplicaciones. Simplemente son puntos de entrada o de comunicación entre diferentes sistemas. Estos sistemas pueden estar en el mismo ordenador en diferentes capas de software, o pueden estar distribuidos en diferentes ordenadores.

Cuando hablamos de API Rest o Restful hablamos casi de lo mismo. Rest se refiere a que se ejecuta sobre HTTP/HTTPS, mientras que Restful se refiere a que es un servicio web. Una API Restful entonces es una API que se ejecuta sobre la web atendiendo a las peticiones HTTP/HTTPS.

Un tema importante es que, entre peticiones distintas no se guarda ningún estado, con lo que si por ejemplo tenemos autenticación, se autentica de nuevo en cada nueva petición.

Los tipos de peticiones son:

• GET: para listar uno o varios elementos.
• PUT: para actualizar un elemento.
• POST: para crear nuevos elementos.
• DELETE: para borrar.

Existe una forma especial de referenciar a un elemento en concreto llamado IRI. Por ejemplo si estuviéramos trabajando con información relacionada con localizaciones, la localización número 123 podría referenciarse por ejemplo haciendo:

https://host-donde-corre-la-api.com/api/location/123

Esta IRI es su identificación única.

Qué es la API Platform

La API Platform es un framework de construcción de APIs, hecho con PHP, HTML y JavaScript. Se proporciona como un proyecto completo e independiente, pero también se puede embeber en proyectos ya funcionales. Pudiéndose utilizar también como un componente único al usar sólo su core.

Su página oficial es: https://api-platform.com/

Probando el proyecto completo de la API Platform

Podemos ir a la página de descargas, en GitHub, desde donde podemos descargar la última versión completa. A fecha de hoy desde esta web se pueden descargar: https://github.com/api-platform/api-platform/releases

Si por ejemplo empezamos un proyecto hoy descargando la última versión, tendremos que ceñirnos a usar PHP8 y las últimas versiones de Symfony. Lo siguiente será descomprimir el fichero .zip e instalar los paquetes con Composer ejecutando:

composer install

Construyendo desde cero el proyecto, instalando los componentes

Una buena alternativa es construir el proyecto ciñéndolo a los requerimientos de PHP que queramos. Para esto no hay más que seguir el proceso natural de cualquier otro proyecto Symfony. Por ejemplo, si vamos a construir una API para almacenar información sobre localizaciones geográficas, podríamos hacer desde consola:

symfony new api
cd api
composer require api-platform/core orm twig asset

Hasta aquí tenemos que haber visto algo parecido a lo de esta imagen anterior, y tendremos lo básico instalado para el proyecto bajo el directorio /api desde donde hayamos ejecutado los comandos. Lo siguiente interesante para instalar es el paquete del maker de Symfony, para ayudarnos a generar códigos fuentes sin picarlos por completo:

composer require --dev symfony/maker-bundle

Ahora tenemos un proyecto Symfony completo, compatible con la versión de PHP que tengamos instalada, y desde donde hayamos lanzado el comando. Si en el servidor tenemos otra versión conviene crear el proyecto desde dicha versión de PHP, si no luego tendremos problemas. También ten en cuenta que si usamos las últimas versiones de PHP, mejor, ya que el rendimiento ha aumentando mucho.

Construyendo la API, un endpoint

La idea general es muy simple. Como todas las API Restful, tendremos tantos elementos administrables desde la API como queramos, y estos elementos permitirán las cuatro operaciones CRUD citadas al principio del post:

• Listar.
• Añadir.
• Editar.
• Borrar.

Vamos a hacer entonces una API que contenga elementos que sean localizaciones geográficas. Entonces, simplemente tenemos que crear una entidad que represente las localizaciones, y configurar la API. Podemos crear fácilmente la entidad con el generador de código fuente de Symfony haciendo así en la consola de comandos o terminal:

php bin/console make:entity Location

Aquí cada uno le puede poner los parámetros que quiera siguiendo las instrucciones como en la imagen siguiente:

Conectando la base de datos

Lo siguiente será en local conectar la base de datos en el proyecto y crearla. Para esto tenemos que configurar el fichero .env.local, o .env.dev, y usar las migraciones de Doctrine para hacerlo lo mejor posible. Un fichero .env.local de pruebas podría editarse para MYSQL poniendo tus configuraciones de la base de datos:

DATABASE_URL="mysql://user:password@127.0.0.1:3306/testing_api?serverVersion=5.7"

Ahora toca ejecutar los comandos de las migraciones y crear finalmente la base de datos:

php bin/console doctrine:database:create
php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate --no-interaction

Ahora podemos comprobar en la BD que realmente se ha creado la tabla relacionada con la entidad Location.

Comprobando el nuevo endpoint

Lo siguiente es arrancar en local la API para ver si ya lo tenemos todo. Podemos arrancar el servidor de desarrollo en local así:

symfony server:start

..en este caso, con la instalación actual tenemos lo siguiente desde el navegador:

En la configuración por defecto, tendremos que la API se podrá acceder bajo el directorio /api. Esto se puede cambiar, tanto para desarrollo, como para tests y producción, usando el sistema de configuraciones normal de Symfony en los directorios y ficheros:

• config/packages/api_platform.yaml
• config/packages/prod/api_platform.yaml
• config/packages/test/api_platform.yaml

Si no especificamos configuraciones por entorno, usará la configuración establecida en config/packages/api_platform.yaml. Lo último para este codekata es ver qué pasa porque no tenemos accesibles las localizaciones. Lo único que resta es declarar como recurso de la API a la entidad Location. Esto se soluciona poniendo en el inicio del fichero src/Entity/Location.php lo siguiente:

<?php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;
use App\Repository\LocationRepository;
use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity(repositoryClass=LocationRepository::class)
 * @ApiResource()
 */
class Location
{
..

Simplemente usando la anotación @ApiResource() lo conseguimos. Esta anotación tiene mucho juego, con lo que se pueden conseguir configuraciones de la API muy elaboradas, pero esto es material para otro post. Ahora comprobamos de nuevo en el navegador y ya lo tenemos todo funcionando:

Terminando, enlaces y referencias

Para continuar, sólo queda remitirte a la documentación oficial de la API Platform que está muy bien:
https://api-platform.com/docs/core/configuration/

Me parece una maravilla la API Platform, así que espero pronto tener tiempo para juguetear más que ella, y volver con más posts.. No dudes en dejar un comentario para cualquier cosa ?