Crear una REST API con autenticación usando Laravel [Capítulo 1]

OBJETIVO

Esta entrada es la primera de una serie de artículos sobre Laravel, uno de los frameworks PHP más populares del momento.

El objetivo de estos artículos es aprender a construir una REST API con autenticación usando Laravel 5.5. Para ello utilizaremos Composer, el gestor de paquetes y dependencias de PHP, y Artisan, una interfaz de línea de comandos que viene con Laravel.

La API que vamos a crear nos permitirá la creación, consulta, actualización y borrado de Usuarios y Artículos, y que estas acciones solo sean realizadas a través de llamadas autenticadas (de usuarios inicialmente registrados en el sistema):

  • Artículo:
    • Título
    • Cuerpo
    • Fecha de publicación
  • Usuario:
    • Nombre
    • Correo electrónico
    • Contraseña

Todo el código necesario para seguir esta guía y construir la REST API se encuentra en GitHub.

CONTENIDO

En este primer artículo abordaremos los siguientes puntos:

PRERREQUISITOS

PASO 1: CONFIGURACIÓN BÁSICA DE UNA APLICACIÓN LARAVEL

Desde la línea de comandos, nos situamos en nuestr directorio de proyectos e instalamos Laravel usando el siguiente comando de Composer:

$ composer global require laravel/installer

Creamos la estructura de la nueva aplicación Laravel tecleando lo siguiente:

$ composer create-project --prefer-dist laravel/laravel laravel-api

Y con esto ya somos capaces de arrancar el servidor y comprobar si la aplicación funciona:

    $ cd laravel-api
    $ php artisan serve
      Laravel development server started: http://127.0.0.1:8000
Laravel - Pantalla de inicio
Laravel – Pantalla de inicio

PASO 2: CONECTAR CON LA BASE DE DATOS

Al crear la estructura de la aplicación, en el directorio de proyectos donde estamos trabajando se habrá creado una nueva carpeta “laravel-api” con la siguiente estructura:

Laravel - Estructura de directorios
Laravel – Estructura de directorios

Debemos introducir las credenciales para que la aplicación pueda acceder a la base de datos (que deberemos tener creada previamente). Esto lo haremos editando el fichero .env que se encuentra en el directorio raíz de la aplicación:

    DB_CONNECTION=mysql
    DB_HOST=127.0.0.1
    DB_PORT=3306
    DB_DATABASE=laravelapi
    DB_USERNAME=username
    DB_PASSWORD=********

Para construir el modelo de datos de los Artículos y la migración asociada, usaremos el siguiente comando de Artisan:

$ php artisan make:model Article -m

La opción -m es la abreviatura de –migration, que le indica a Artisan que la cree automáticamente para nuestro modelo.

Las migraciones en Laravel actúan a modo de control de versiones de la base de datos, y resulta muy útil para modificar y compartir el esquema de datos de la aplicación.

Laravel viene por defecto con dos migraciones, creates_users_table y create_passwords_reset_table. Esta última no la vamos a aprovechar, pero users nos va a ser muy útil en esta guía.

La nueva migración se generará en el directorio ./laravel-api/database/migrations

Vamos a añadir los campos Título y Cuerpo al modelo editando la función up():

El método string crea una columna de tipo VARCHAR, mientras que text genera una de tipo TEXT.

Para que estos cambios se vean reflejados en nuestra vase de datos, lanzamos el siguiente comando:

$ php artisan migrate

Volvemos a nuestro modelo, y vamos a indicar qué campos de un Artículo son editables. Para ello usaremos el campo $fillable en la clase Article que se ha generado automáticamente en ./laravel-api/app/Article.php:

PASO 3: POBLANDO LAS TABLAS DE ARTÍCULOS Y USUARIOS

Vamos a poblar o sembrar (‘seed‘ en inglés) las tablas con datos de prueba para poder testear nuestra aplicación. Laravel trae Faker, una librería que nos ayuda en esta tarea. Para crear nuestra primera siembra:

$ php artisan make:seeder ArticlesTableSeeder

Al finalizar este comando, tendremos un nuevo fichero en ./laravel-api/database/seeds/ArticlesTableSeeder.php. Lo editamos para darle algo de funcionalidad y que nos quede con este aspecto:

Ejecutamos el comando seed para realizar la siembra:

$ php artisan db:seed --class=ArticlesTableSeeder

Y si inspeccionamos el contenido de la tabla en la base de datos, veremos que ya cuenta con 50 líneas:

Tabla de Artículos tras la siembra
Tabla de Artículos tras la siembra

Repetimos el proceso para los Usuarios, primero creando la siembra:

$ php artisan make:seeder UsersTableSeeder

A continuación preparamos el código para sembrar Usuarios:

Y luego ejecutando la siembra:

$ php artisan db:seed --class=UsersTableSeeder

Y como resultado, observamos en la base de datos qué tal ha ido la cosecha:

Tabla de Usuarios tras la siembra
Tabla de Usuarios tras la siembra

PASO 4: RUTAS Y CONTROLADORES CRUD

En los pasos anteriores hemos generado una aplicación esqueleto con Laravel, la hemos conectado a la base de datos y hemos poblado sus tablas a través de varias siembras.

En este cuarto paso vamos a dotar a nuestra aplicación de la clásica funcionalidad CRUD: crear (Create), recuperar (Retrieve), actualizar (Update) y borrar (Delete) items de la base de datos.

En primer lugar vamos a implementar las rutas, que serán las URL que se enviarán a nuestra aplicación para implementar cada una de las operaciones descritas. Con Laravel es tan sencillo como editar el fichero ./laravel-api/routes/api.php:

Vamos a mover este código a su propio controlador. Generamos el controlador con el siguiente comando de Artisan:

$ php artisan make:controller ArticleController

Y copiamos el código en el fichero generado ./laravel-api/app/Http/Controllers/ArticleController.php:

De tal forma que el fichero ./laravel-api/Routes/api.php nos quedará de esta manera, indicando para cada ruta el controlador y método que deben llamarse:

Los métodos del controlador retornan datos en formato JSON y un código HTTP para que lo procese la aplicación cliente. Estos son algunos de los códigos HTTP de retorno más comunes:

  • 200: OK. Código estandar de que todo ha ido bien y opción por defecto.
  • 201: Object created. Muy útil para las operaciones de guardado.
  • 204: No content. Cuando una acción se ejecuta con éxito, pero no hay contenido que devolver.
  • 206: Partial content. Útil cuando se devuelven resultados paginados.
  • 400: Bad request. Respuesta estándar cuando una petición no supera la validación.
  • 401: Unauthorized. Autenticación requerida.
  • 403: Forbidden. El usuario se ha autenticado, pero no tiene los permisos necesarios para realizar la acción.
  • 404: Not found. Laravel lo devuelve automáticamente cuando no se encuentra un recurso.
  • 500: Internal server error. Nunca debería retornarse este valor explícitamente, pero si algo inesperado falla, esta es la respuesta que recibirá el usuario.
  • 503: Service unavailable. Bastante descriptivo por sí mismo. Nuestra aplicación tampoco debería devolver explícitamente este código.

PASO 5: PROBANDO LA API CON POSTMAN

Siguiendo las instrucciones de estos 4 pasos ya tenemos una API que nos permite hacer la gestión básica de Artículos. Si queremos verla en acción, para probarla y ver que todo funciona correctamente, podemos usar Postman.

Postman es una potente herramienta para probar API’s con una interfaz gráfica muy intuitiva y sencilla de manejar. Una forma sencilla de empezar con Postman es instalar la extensión para Chrome, aunque es recomendable instalar la aplicación nativa para nuestro sistema operativo ya que la extensión ha sido descontinuada recientemente.

Una vez arrancada la herramienta, su uso es tan sencillo como ir introduciendo URL’s en la barra de direcciones que contiene, e ir cambiando el método en el desplegable que usa a su izquierda para alternar entre peticiones GET, POST, PUT y DELETE (por poner las más comunes).

Así, si queremos recuperar todos los Artículos de la base de datos, hacemos la siguiente llamada a nuestra API con el método GET, tal como lo hemos configurado en nuestras rutas y controladores en el paso 4:

[GET] http://localhost:8000/api/articles/

Postman - Recuperar todos los Artículos [GET]
Postman – Recuperar todos los Artículos [GET]
Podemos testear el resto de rutas:

  • Recuperar el artículo con identificador 12:
[GET] http://localhost:8000/api/articles/12
Postman - Recuperar un Artículo [GET]
Postman – Recuperar un Artículo [GET]
  • Crear un nuevo artículo:
[POST] http://localhost:8000/api/articles/

Deberemos añadir los pares clave-valor para ‘title‘ y ‘body‘ en el apartado “Body”.

Postman - Crear un Artículo [POST]
Postman – Crear un Artículo [POST]
  • Actualizar el título del artículo con identificador 51:
[PUT] http://localhost:8000/api/articles/51

Deberemos añadir el par clave-valor en el apartado “Body”.

Postman - Actualizar un Artículo [PUT]
Postman – Actualizar un Artículo [PUT]
  • Borrar el artículo con identificador 51:
[DELETE] http://localhost:8000/api/articles/51
Postman - DELETE
Postman – DELETE

RECOPILACIÓN

En este primer artículo de la serie “Crear una REST API con autenticación usando Laravel” hemos aprendido a crear la estructura básica de una aplicación Laravel, a conectarla con una base de datos, a poblar las tablas y a implementar las rutas y controladores básicos para soportar una operativa CRUD básica.

Para ello hemos utilizado herramientas como Composer, el gestor de paquetes y dependencias para PHP, una potente interfaz de línea de comandos de Laravel, y Postman, una herramienta muy útil para testear REST API’s.

En los siguientes artículos veremos cómo implementar autenticación vía API con Laravel, rutas y controladores para registrar y logear usuarios, así como el uso de middlewares para restringir el acceso a la API.

Si tienes cualquier duda o problema a la hora de comprender alguno de los pasos, exponla en los comentarios y te responderé. Y si ya tienes experiencia haciendo REST API‘s o con Laravel, te invito a compartir tu experciencia e impresiones sobre este artículo en los comentarios. Compartamos conocimiento y ¡crezcamos juntos!

Desarrollo WebSoftware Libre