Crear un API Rest en Laravel

En este artículo vamos a aprender a crear una API REST con Laravel, es decir, una aplicación que nos permita trabajar con una base de datos y después poder consumirla mediante cualquier otro lenguaje o un framework fronted de terceros, esos datos.

Empecemos por el principio para obtener un poco de contexto, ¿Te parece? 

¿Qué es una API REST?

Una API de REST, o API de RESTful, es una interfaz de programación de aplicaciones (API o API web) que se ajusta a los límites de la arquitectura REST y permite la interacción con los servicios web de RESTful. El informático Roy Fielding es el creador de la transferencia de estado representacional (REST)

En otras palabras, las API le permiten interactuar con una computadora o un sistema para obtener datos o ejecutar una función, de manera que el sistema comprenda la solicitud y la cumpla.

¿Por  qué es importante aprender a usarlas? 

Las API´s permiten la interacción entre programas y la “reutilización de funcionalidades” sin la necesidad de compartir todo el código de software

Pero, ¿Qué os parece si nos metemos un poco en el código creando nuestra propia API? Pues no perdamos más tiempo... adelante!!

Creación de una API REST con Laravel

El primer paso será crear un proyecto desde 0. Para eso lo único que vas a necesitar es tener instalado un entorno como XAMPP,  MAMP, tu propio contendor, etc. Necesitaras el manejador de paquetes de PHP,  Composer . Por último, mi recomendación es que tengas instalado Postman, para poder realizar fácilmente las pruebas a nuestra API.

Una vez superado estos escollos, procederemos a iniciar nuestro proyecto ejecutando el siguiente comando:

composer create-project laravel/laravel apirestfull

¿Al ejecutar este comando que ha ocurrido?,  Composer creara una carpeta con el nombre  que le hayamos indicado al ejecutar el create-project,  en mi caso, apirestfull.  Dentro de la carpeta, habrá copiado toda la estructura de carpetas en la que se basa Laravel. Dentro del proyecto,  también se habrá creado un archivo .env (archivo de configuración que sirve para poner nuestras claves a base de datos o servicios externos). Entre otros muchos más archivos.

La versión de Laravel usada para este ejemplo es la 8.75 y para PHP la versión 8.0

Ahora accederás a la carpeta de tu proyecto desde el editor de código que uses, en mi caso será VSC. El proyecto va a girar entorno a una API de libros donde podremos hace consultas de un libro, todos o eliminar uno. Por lo tanto lo primero que haremos será crear el modelo Book. Para eso ejecutaremos el comando:

php artisan make:model Book -cmf

¿Qué significa el parámetro -cmf? En el momento de crear nuestro archivo para el modelo, también vamos a crear los archivos Controller, Migration, y Factory. Un poco más adelante explicaremos para que sirven cada uno de estos archivos.

Comenzaremos configurado nuestro modelo Book:

Añadimos nuestros atributos fillable, la relación con el modelo User que ya viene creado por defecto en Laravel, además de una función para transformar el atributo descripción cuando accedamos a él. Lo que realizaremos es mostrar un máximo de 120 caracteres.

Configuramos la migración del modelo Book con sus campos y su relación con el modelo User.

Y por último, configuramos el Factory de Book, para crear registros falsos que usaremos para realizar nuestras pruebas.

El Factory de usuario ya viene creado por defecto con la instalación del proyecto,  solo debemos crear el de books.

A continuación configuramos el Seeders para lanzar los Factories cuando ejecutemos las migraciones. Crearemos 10 usuarios y 50 libros:

Antes de ejecutar las migraciones, debemos tener nuestra base de datos creada y el archivo .env configurado hacía esa BD.

Generamos las migraciones con todos los datos de prueba que hemos configurado, ejecutando el comando:

php artisan migrate --seed

Ahora pasaremos a crear nuestros controladores, con sus recursos y rutas.

En primer lugar crearemos un controlador, pero en una ruta especifica dentro de App\Http\Controller. Además le vamos agregar dos parámetros a la hora de crear el controlador. El primero --api, con este parámetro, nos creara todos los métodos necesarios para cubrir todas las peticiones que nos puede llegar. El segundo parámetro, --model, relacionará nuestro controlador a un modelo especifico, en este caso con el modelo Book.

 php artisan make:controller  Api/V1/BookController --api --model=Book

El archivo recurso, también lo crearemos en una ruta especifica dentro del directorio App\Http\Resource.

php artisan make:resource  V1/BookResource

¿Por que creamos este archivo? Lo que hacemos con este proceso, es añadir una capa de transformación entre nuestro modelo y su respuesta en JSON.  Por ejemplo, puede que desees mostrar ciertos atributos para un subconjunto de usuarios y no para otros, o puede que desees incluir siempre ciertas relaciones en la representación JSON de sus modelos.

Pasemos a las configuraciones de estos archivos que hemos creado. Controlador, para este ejemplo vamos a usar únicamente tres métodos, index, show y destroy.

Como puedes comprobar, en el método index y show, llamamos a nuestro recurso BookResource. Para ello debemos llamar a la clase, tal y como aparece en la primera línea de la imagen.

En el archivo BookResource,  únicamente añadiremos está información:

!Animo que ya queda menos! 

Ahora pasaremos a configurar nuestro archivo de rutas. Para eso iremos al fichero routes\api.php

Importaremos nuestro controlador al principio del fichero,  le daremos un Alias (esto último no es necesario) y debajo definiremos nuestras rutas:

use App\Http\Controllers\Api\V1\BookController as BookV1;

Route::apiResource('v1/books', BookV1::class)
      ->only(['index','show', 'destroy'])
      ->middleware('auth:sanctum');

Lo que hemos realizado es definir todas las rutas con "apiResource", pero especificamos que de momento solo vamos tener activas las rutas index, show y destroy con el atributo "only". Por último agregamos el middleware de autentificación con la librería Sanctum. Con esto protegeremos el acceso a las rutas de nuestra API, convirtiéndola en una API privada.

Instalar Laravel Sanctum

Laravel Sanctum proporciona un sistema de autenticación para SPA (aplicaciones de una sola página), aplicaciones móviles y API simples basadas en tokens. Sanctum permite que cada usuario de su aplicación genere múltiples tokens API para su cuenta. A estos tokens se les pueden otorgar habilidades / alcances que especifican qué acciones pueden realizar los tokens.

Lo normal es que en las últimas versiones de Laravel, ya venga integrado el paquete de Sanctum. No obstante, os detallo como sería la instalación de forma manual. 

Para su instalación ejecutaremos el comando 

composer require laravel/sanctum

Al descargar esta librería, se generan una migraciones necesarias para la creación de una tabla que gestionará la autentificación de Sanctum. Por lo tanto, tendremos que ejecutar el comando de las migraciones:

php artisan migrate

Si no se ejecuta ninguna migración significa que Sanctum ya se instaló al comienzo del proyecto y nos  genero la tabla cuando ejecutamos las migraciones. Accede a tu base de datos y asegúrate de que tienes la tabla "personal_access_tokens"

Ahora crearemos un controlador que gestione el acceso y autenticación de nuestra API. Se va a crear en la ruta de la API, pero fuera de la versión.

php artisan make:controller Api/LoginController

Avancemos en nuestras configuraciones. En routes\api.php, generamos la ruta Login.

Route::post('login', [App\Http\Controllers\Api\LoginController::class, 'login']);

Ahora accedemos a LoginController y agregamos el siguiente código:

En el modelo User debemos asegurarnos que se está llamando a la librería de Sanctum y le indicamos que el proceso de autenticación será por tokens. Debería incluir las siguientes líneas:

namespace App\Models;
use Illuminate\Contracts\Auth\MustVerifyEmail;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;

Ahora sí, ya hemos terminado toda la configuración y nuestra API ya está creada. Vamos a ponerla a prueba desde Postman !

 Postman es una aplicación que nos permite realizar pruebas API. Es un cliente HTTP que nos da la posibilidad de testear 'HTTP requests' a través de una interfaz gráfica de usuario, por medio de la cual obtendremos diferentes tipos de respuesta que posteriormente deberán ser validados

Lo primero que tendremos que hacer es autentificarnos para obtener el token que nos permitan acceder a la API. Para eso, nos autentificaremos usaremos el método POST con email y contraseña de un usuario existente en nuestra base de datos. Para obtener ese usuario,  accede a la tabla de usuarios y copia el email de cualquiera de los registros que creamos al principio, y la clave que usaras será "password". Laravel por defecto, pone como contraseña "password", a todos los usuarios que crea como datos de prueba.

La petición debería quedar así:

Una vez realizada la petición y si todo ha ido bien, nos devolverá una respuesta con el token generado y el mensaje  Success. Tal y como lo configuramos.

Ya nos hemos autentificado en nuestra pequeña aplicación, Enhorabuena. Ahora probemos a realizar alguna consulta a nuestra API.

Copia el token generado e  inclúyelo en el apartado de Authorization.

Para eso vamos a Postman, cambiamos el método a GET y  añadimos la url que hemos definido en las rutas para obtener un libro. En Authorization, vamos a Type y seleccionamos "Bearer Token",  y en el campo Token, pegamos el código generado en el paso anterior, así:

En la pestaña de  body marcamos none, y lanzamos la consulta

El resultado que nos muestra es la información del libro con Id 1. En este caso el titulo y descripción, que es la información que le configuramos en el fichero BookResource. Fácil verdad?

Si quisiéramos obtener todos los libros, la consulta sería al endpoint 

GET http://localhost:8000/api/v1/books/

Por último, para probar la tercera ruta que tenemos configurada, que es la de eliminar un recurso, le pasaríamos el id del recurso que queremos eliminar, al siguiente endpoint:

DELETE http://localhost:8000/api/v1/books/1

Con esto habríamos dado los primeros pasos sobre el funcionamiento de un API y lo fácil que es ponerla en marcha con Laravel. Si deseas seguir ampliando este proyecto o ver alguna parte más en detalle, te dejo todo el repo  aquí, para que te lo puedas descargar o revisarlo.  Además de lo visto aquí, en el repo de Github también podrás encontrar:

• La Versión 2 de  la API. Con un archivo de recursos más completo para esa versión.
• Una vista web (Con su controlador y ruta web) para la visualización de todos los libros por pantalla.
• Además Tailwindcss instalado en el proyecto.

Recuerda que si te ha gustado esta entrada y crees que puede ser de utilidad a la comunidad, no dudes en compartirlo. Gracias y feliz código!!

Fuentes:

Redhat, Italo Morales