Como construir un RESTful API con Symfony 4 + JWT – Parte 3

RESTful API con Symfony 4 + JWT

Continuamos con esta serie de posts donde explico de manera detallada como construir un RESTful API con Symfony 4 + JWT.

En el post anterior, nos dedicamos a instalar Symfony 4, a instalar los bundles y paquetes necesarios para nuestra aplicación y a su vez, creamos las entidades requeridas para este caso práctico.

Ya con lo anteriormente listo, vamos a proceder con el desarrollo del RESTful API, para ello seguiremos los siguientes pasos:

  1. Configuración de los bundles para nuestro RESTful API.
  2. Creación de los servicios (endpoints) del API.
  3. Test de los servicios del API con Postman.

 

Configuración de los bundles para nuestro RESTful API.

Iré colocando la configuración que se debe establecer para cada bundle y componente que sea necesario en función de hacer que nuestro RESTful API quede correctamente configurado y funcional.

Configuración para el bundle JWT:

Crear certificados SSH para JWT

Para esto debemos ejecutar los siguientes comandos:

Parámetros de JWT en archivo .env se establecen de la siguiente forma:

Parámetros del paquete Lexik/jwt-authentication-bundle en el archivo “config/packages/lexik_jwt_authenticantion.yaml” se establecen de la siguiente forma:

El archivo security.yaml ubicado en “config/packages” debe quedar de la siguiente manera:

Creación de un Controlador para nuestro API

Crearemos el controlador “ApiController” para generar todos los métodos relacionados con nuestro API. El controlador lo crearemos en el directorio “src/Controller“. Inicialmente nuestro controlador debe lucir así:

Configuración para el bundle nelmio/api-doc-bundle:

Archivo “config/packages/nelmio_api_doc.yaml” debe lucir así:

Agregar la siguiente ruta en nuestro archivo “config/routes.yaml“:

El resto de los bundles no necesitan configuración ya que con la que Symfony Flex genera por nosotros automáticamente, es suficiente para el desarrollo de nuestra aplicación de ejemplo.

Creación de los servicios (endpoints) del API.

Ya tenemos todo listo para proceder a crear los endpoints del API. Recordando un poco las URI´s diseñadas anteriormente tenemos:

Para definir un endpoint en Symfony es sumamente sencillo, ya que con la ayuda del bundle FOSRestBundle y las anotaciones que pone a disposición para tal motivo, es tarea fácil. Solo debemos entonces crear un método para cada ruta diseñada anteriormente y agregar estas anotaciones para indicarle a Symfony como debe comportarse al momento de que hagamos cada una de las peticiones (Requests) a nuestro API.

Adicionalmente, el bundle ApiDocBundle nos provee también de ciertas anotaciones para documentar nuestro API (cosa que es sumamente importante y más cuando se trate de un API enorme), las cuales este bundle se encargará de digerir dicha información y ponernos a disposición una ruta (suele ser /api/doc) para consultar dicha documentación.

A continuación muestro como queda nuestro controlador ApiController con cada uno de los endpoints definidos y las anotaciones respectivas.

Y con esto, tenemos listo nuestro RESTful API, siguiendo muchas de las buenas practicas mas comunes como la documentación de nuestro API, convenciones en nuestras URI’s, entre otros. Podemos resumir que a pesar de haber tenido que instalar varios paquetes, componentes y dependencias, al final del camino sigue siendo bastante sencillo utilizar Symfony como proveedor de nuestro RESTful API sobre todo puesto que gracias a la forma que nos ha inculcado este framework, estaremos siempre alineados y trabajando de forma ordenada y pensando siempre en que en mucho de los casos, seremos equipos de trabajo quienes uniremos esfuerzos en un mismo proyecto para llevar a cabo los objetivos.

Otro tema importante que no tocaré a fondo en este post es sobre la documentación de API´s mediante el uso del bundle para symfony: nelmio/api-doc-bundle. Te recomiendo leer un poco en su documentación para entender un poco más a detalle sobre todas las anotaciones que pone a nuestra disposición para tal motivo.

Ahora solo resta probar nuestro RESTful API para corroborar que cada verbo de HTTP este funcionando como debe, y adicionalmente, que nuestro código este funcionando como se requiere.

Test de los servicios del API con Postman.

Postman es una herramienta maravillosa para ayudarnos en el proceso de desarrollo de nuestro API, ya que permite visualmente, y con muchísimas opciones interesantes, diseñar, gestionar y probar nuestro API de forma rápida y sencilla. Te recomiendo leer mi post sobre esta maravillosa herramienta: Postman: Como gestionar y construir tus API’s de forma rápida y sencilla para conocer un poco más de lo que nos ofrece esta interesante y super útil herramienta.

Antes de empezar con las pruebas quiero acotar lo siguiente:

  • Para este proyecto, en mi caso particular configuré mi servidor web con un virtual host el cual responde a la siguiente url: http://api.my-kanban.com. Tú también puedes configurar uno propio o bien acceder utilizando el path común http://localhost/my_kanban.
  • Para visualizar como quedó la documentación de nuestro API, basta con acceder a la ruta /api/doc, es decir, http://localhost/my_kanban/api/doc.
  • No es obligatorio probar nuestro API utilizando Postman, podemos simplemente utilizar cUrl desde nuestra terminal o Httpie el cual es un programa que corre desde consola y también nos provee de forma rápida una manera de probar nuestros endpoints.

Voy a explicar brevemente como realizar las pruebas con Postman y para que de cierta forma puedan entender como funciona la seguridad de JWT y como es requerido en nuestros servicios que requieren que estemos autenticados según la configuración realizada en el archivo security.yaml.

Lo primero es hacer una petición POST a nuestro endpoint de register cuyo path es /api/register. Lo haremos de la siguiente forma:

La ruta en mi caso es http://api.my-kanban.com/api/register

Postman

Luego que hayamos registrado un usuario, procederemos a autenticarnos para que podamos obtener el Token necesario para poder realizar las siguientes peticiones a nuestros endpoints protegidos.

En la sección de Headers, debemos agregar la cabecera Content-Type con el valor application/json

Postman

Y en la sección del Body, colocar los siguientes parámetros para enviar nuestros datos de acceso:

Postman

Hacemos click sobre el botón Send, y si todo va bien, nos debe responder el servicio con el respectivo token:

Postman

Ahora, con este token, podemos realizar las siguientes peticiones a nuestros endpoints, enviendo dicho token en los headers de cada una. Para no extender tanto el post, voy a solicitar el listado de boards utilizando el método GET y el path /api/v1/board, primero sin enviar el token, luego enviándo el correcto y uno fake para demostrar que la seguridad esta funcionando como debe ser.

Vale la pena destacar, que el token se debe enviar en el header de la petición en la variable “Authorization” y cuyo valor debe ser el token precedido por la palabra “Bearer”.

GET http://api-my-kanban.com/api/v1/board sin token

Postman

GET http://api-my-kanban.com/api/v1/board con token

Postman

GET http://api-my-kanban.com/api/v1/board con token inválido

Postman

Como podemos observar, nuestros servicios están funcionando. Podemos registrarnos, hacer login para obtener el respectivo token, y con este, realizar peticiones a los demas endpoints protegidos para realizar la funcionalidad completa de nuestra aplicación.

Te invito a que realizes como tarea el resto de las peticiones siguiendo como ayuda los endpoints definidos en la documentación del API (http://localhost/my_kanban/api/doc). 

Adicionalmente, te dejo todo el código del proyecto en mi repositorio de GitHub.

Y hasta aquí llega esta pequeña pero nutritiva serie de posts sobre como crear un RESTFul API con Symfony 4 + JWT.

Si te gustó este post, ayúdame a que pueda servirle a muchas más personas, compartiendo mis contenidos en tus redes sociales.

Espero que este post haya sido de gran ayuda para ti, y como siempre, cualquier inquietud o duda que tengas, puedes contactarme por cualquiera de las vías disponibles, o dejando tus comentarios al final de este post. También puedes sugerir que temas o post te gustaría leer a futuro.