Desarrollar una API REST con Symfony

1. Los conceptos de REST

REST es un acrónimo de REpresentational State Transfer. La idea es colocar una aplicación en un estado de representación de sus recursos, en función de la acción solicitada. Esta arquitectura de construcción de aplicaciones se basa en el protocolo HTTP y la noción de recurso.

REST no es estrictamente hablando un estándar, en la medida en que el W3C (World Wide Web Consortium) no lo define como tal. Sin embargo, utiliza estándares W3C existentes, tales como:

1. Introducción a JSON

El formato JSON (JavaScript Object Notation) es un formato de datos textuales inspirado en la notación de objetos JavaScript, creado a partir de 2002 por Douglas Crockford. El propósito del formato JSON es facilitar el intercambio de datos aplicativos en la Web, intercambios que con anterioridad se basaban sistemáticamente en XML. Este último se considera demasiado detallado y, por lo tanto, consume ancho de banda, con lo que JSON es una alternativa más ligera para estos intercambios.

...  
"clave1": "Valor de clave1",  
"clave2":...

1. El servicio de serializador

Antes de permitirnos manipular datos en JSON, es necesario instalar el serializador Symfony. Este serializador estará disponible como un servicio inyectable en las clases de su aplicación.

Para instalar este servicio denominado serializer, hay que ejecutar una recipe Flex con el siguiente comando:

composer require symfony/serializer-pack 

Una vez instalado, el servicio se puede inyectar en las acciones del controlador a través de la interfaz Symfony\Component\Serializer\SerializerInterface:

namespace App\Controller;   
   
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\Serializer\SerializerInterface;   
   
class DefaultController extends AbstractController   
{   
   public function index(SerializerInterface $serializer)   
   {   
   ...

1. Contenido y cabeceras de peticiones

Durante la manipulación de los datos entrantes, es necesario poder recuperar las cabeceras y el cuerpo de la petición.

Las cabeceras contienen el tipo de datos enviados por el cliente. Se puede acceder a esta información a través del método getContentType().

En el caso de que los datos JSON se pasen en la petición, se pasan en el cuerpo; se puede acceder a este contenido con el método getContent().

Así es como se podría estructurar el código de una acción que recibe un flujo JSON en HTTP POST:

/**   
 * @Route(   
 *      "/api/articulo",    
 *      name="api_articulo_crear",   
 *      methods={"POST"}   
 * )   
 */   
public function crear(   
   Request $request, SerializerInterface $serializer   
): Response   
{   
   // Controlamos el formato de datos entrante...   ...

1. Los límites del navegador web

Como parte del desarrollo de una aplicación web tradicional que utiliza vistas, es bastante sencillo comprobar cómo se representan las páginas usando su navegador web.

Para una API REST es diferente. De hecho, siempre podemos usarla para probar acciones que reaccionan sobre las peticiones HTTP de tipo GET, pero para las peticiones POST, PUT y DELETE es complicado; el navegador no se ha previsto para esto.

Por supuesto, podemos crear pruebas funcionales basadas en PHPUnit y los objetos Client y Crawler, como se comenta en el capítulo Probar su aplicación Symfony, pero sigue siendo práctico poder consultar las respuestas devueltas por la API en las fases de desarrollo. Para esto, utilizaremos herramientas dedicadas a las pruebas de API REST.

2. Herramientas

Las herramientas para probar las API REST solo son generadores de peticiones HTTP que permiten recibir y explorar respuestas HTTP. Como herramientas reales para el desarrollador, le permiten agrupar peticiones en proyectos, así como especificar las cabeceras y el contenido de estas peticiones.

1. Presentación

API Platform es una librería que le permite crear API REST de manera sencilla. Esta librería es mantenida por Les Tilleuls.coop (https://les-tilleuls.coop), una empresa francesa. Hay un paquete que permite utilizar toda la flexibilidad de API Platform en Symfony y, de esta manera, crear API REST en un tiempo récord. 

2. Instalación

Para tener el paquete API Platform en su proyecto, debe ejecutar la recipe Symfony correspondiente usando el comando:

composer requiere api 

Una vez que se ejecuta la recipe, API Platform está en su lugar. Puede validar la instalación navegando a la dirección http://<misitio>/api.

Por el momento, no hay operaciones disponibles, pero esto va a cambiar rápidamente con la ayuda de algunas anotaciones en las entidades Doctrine de la aplicación.

3. Configurar API Platform

Más allá de la librería instalada en la carpeta vendor/ del proyecto Symfony, la instalación de API Platform proporciona otros archivos, incluyendo:

Ejemplo de personalización:

api_platform:   
    title: "API REST para MiDiario"   
    description: "API utilizable para la aplicación móvil MiDiario" 
   version: '1.0.0'   
    mapping:   ...