En este artículo vamos a crear una API usando Laravel en conexión con PostgreSQL.
Si no tienes Laravel, puedes ver cómo instalarlo accediendo a nuestro artículo Instalando y Configurando Laravel en Windows, Linux y Mac.
En uno de nuestros últimos artículos enseñamos a instalar Postgres y también creamos una primera tabla. Puedes acceder a ese contenido haciendo clic aquí.
Será con base en esta Base de Datos que crearemos nuestra API.
Iniciando la API
Para iniciar un proyecto en Laravel, vamos a usar el siguiente comando: laravel new hcode-api-users.
Después de crear nuestra aplicación, vamos a accederla en la Terminal con el comando cd hcode-api-users y realizar la configuración de la Base de Datos. Para ello, vamos a editar el archivo .env en la raíz de nuestro proyecto, informando las credenciales de nuestra Base. Quedará así:
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=hcodedb
DB_USERNAME=postgres
DB_PASSWORD=root
Además, como vamos a realizar una conexión con Postgres, necesitamos verificar si nuestro PHP tiene las DLL de esta Base de Datos definidas en nuestro archivo de configuración. Si estás usando XAMPP, puedes verificar esta configuración en el archivo xampp/php/php.ini. Las dos líneas siguientes deben estar sin comentarios:
extension=pdo_pgsql
extension=pgsql
Ahora que toda la configuración inicial está realizada, vamos a iniciar el servidor de la API. Para ello, vamos a ejecutar el comando php artisan serve en nuestra Terminal. Se devolverá el siguiente mensaje en la Terminal:
Creando la primera ruta
La primera ruta que crearemos será la ruta para listar los usuarios. El archivo de rutas en Laravel se encuentra en la carpeta routes. Vamos a editar el archivo api.php. Este archivo hace uso de la clase Route. Tiene un método estático para cada método de solicitud HTTP. Para listar usuarios, usamos el método GET. De esta forma, añadiremos el siguiente código en nuestro archivo:
Route::get('users', function() {
return '¡Funcionando!!!';
});
Explicando: el primer parámetro para el método es la ruta en sí, es decir, “users”. El segundo parámetro es una función que se ejecutará al acceder a la ruta. En este caso, solo devolveremos una cadena.
Para probar esta ruta, necesitamos acceder a la URL localhost:8000/api/users en nuestro navegador. Note que informamos “/api”, que es el nombre de nuestro archivo PHP. Al acceder a esta dirección en el navegador, vemos el siguiente resultado:
Excelente, nuestra ruta funcionó. Muy simple, ¿no crees?
El siguiente paso es dejar esta ruta dinámica. Después de todo, queremos listar los usuarios de la Base, no solo devolver un mensaje estático. Esto nos lleva al siguiente recurso de Laravel.
Listando los Usuarios
Laravel utiliza el patrón MVC (Modelo Vista Controlador). De acuerdo con este patrón, en lugar de dejar la regla de negocio explícita en las rutas de nuestra aplicación, debemos incluirla en una clase específica, nuestros Controllers. Será a través de ellos que devolveremos los usuarios para nuestra ruta.
Podemos crear un Controller a través de la línea de comando, usando php artisan, informando a continuación el nombre del Controller que estamos creando. Vamos a ejecutar el siguiente comando:
php artisan make:controller UsersController
Nuestro Controller será creado automáticamente en la carpeta app/Http/Controllers. Se recomienda que siempre creemos Controllers en plural. Esto se considera una buena práctica.
Nuestro Controller fue creado con éxito. Sin embargo, no es el responsable de ir hasta la Base de Datos y traer los datos. Esta función es ejercida por el Model, otra capa de la estructura MVC. Podemos decir que el controller es quien hace el “medio de campo” para traer los datos para la ruta. Pero quien va a buscar esos datos es el Model.
Para crear un Model, podemos usar los recursos de php artisan nuevamente. Vamos a ejecutar el siguiente comando:
php artisan make:model User
Note que el Model se crea en singular, y esto también se considera una buena práctica. Cuando ejecutemos este comando, se devolverá un error, informando que este Model ya existe. Esto ocurre porque el Model con nombre “User” es uno de los que Laravel nos trae por defecto. Sin embargo, si necesitamos crear otros Models, podemos usar el mismo comando.
Ahora que tanto el Controller como el Model están creados, vamos a conectar uno con el otro. Vamos a hacer esto en el archivo UsersController.php. Crearemos un método llamado index(), que será lo que iremos a informar en el archivo de rutas.
Este método realizará la llamada al método all(), que viene del Model User. Este método tiene como objetivo traer todos los registros de la tabla de usuarios. Nuestro código quedará así:
use App\User;
public function index() {
return User::all();
}
Ahora vamos a realizar la llamada a este método en nuestro archivo api.php. Quedará así:
Route::get('users', "UsersController@index");
Explicando: nosotros sustituimos la función que estábamos ejecutando antes por la llamada a la clase UsersController y al método index, que fueron separados por el símbolo de arroba (@).
Ahora, al acceder a la misma dirección en el navegador, vemos el siguiente resultado:
Nuestros usuarios están siendo listados a través de nuestra API. Pero note que en ningún momento ejecutamos un comando SELECT con PHP, de manera imperativa. Solo necesitamos crear los métodos en nuestras clases, de manera declarativa, y Laravel nos trajo los datos deseados. ¡Increíble, ¿no es así?
Creando un Usuario
Ahora vamos a programar la creación de un usuario a través de nuestra API. Comenzaremos por crear el método de nuestro Controller. Lo llamaremos store(). Tendrá el siguiente código:
public function store(Request $request) {
$user = User::create([
"name"=>$request->input("name"),
"email"=>$request->input("email")
]);
return $user;
}
Explicando: este método espera como parámetro la solicitud de nuestro cliente, que en Laravel está representada por la clase Request. Esta clase tendrá toda la información publicada, como el nombre y el email del nuevo usuario.
Nuevamente hacemos uso del Model User y llamamos su método create(), otro recurso nativo de Laravel, que es el responsable de crear el nuevo registro en la Base. Informamos a este método un array con los datos que queremos insertar. Note que usamos el método input() de la clase Request. Este método es el responsable de identificar de hecho el valor de lo que ha sido publicado por el usuario.
Ahora llamaremos a este método a través de nuestro archivo de rutas. Haremos esto mediante la siguiente línea de código:
Route::post('users', "UsersController@store");
Note que una vez más hicimos uso de la ruta “users”. Sin embargo, ahora con el método post().
Para probar esta ruta, podemos usar Insomnia, un REST Client muy poderoso. Enseñamos cómo realizar su instalación y mostramos algunos de sus recursos en el artículo Usando Insomnia para probar las solicitudes de nuestras APIs.
Vamos a acceder a él y crear una nueva solicitud:
Le pondremos el nombre “Hcode API POST” a esta solicitud:
Dejaremos claro que esta es una solicitud POST y definiremos que el cuerpo de la solicitud será del tipo “Form URL Encoded”:
Ahora necesitamos informar los campos que enviaremos y el valor de cada uno de ellos:
El siguiente paso es definir la URL que iremos a acceder:
Finalmente, solo haz clic en “Send”. Cuando hacemos esto, vemos el siguiente error en Insomnia:
Este error ocurre porque Laravel exige que tengamos dos columnas estándar en todas las tablas que creemos. Estas columnas son “updated_at” y “created_at”. Son constantemente actualizadas por Laravel.
Así, vamos a acceder a nuestro Postgres y añadir esas columnas a la tabla users. Iremos a ejecutar el siguiente comando:
ALTER TABLE users
ADD COLUMN updated_at TIMESTAMP DEFAULT NULL,
ADD COLUMN created_at TIMESTAMP DEFAULT NULL;
Ahora, al enviar la solicitud nuevamente, vemos el siguiente resultado:
Perfecto. ¡Nuestros datos fueron insertados correctamente.
Editando un Usuario
Para editar un usuario, vamos a crear en nuestro Controller un método llamado update(). Este esperará como parámetro los datos informados por la solicitud, pero también la información del usuario ya existente que queremos alterar. Su estructura será la siguiente:
public function update(Request $request, User $user) {
$user->name = $request->input('name');
$user->email = $request->input('email');
$user->save();
return $user;
}
Explicando: el valor de las propiedades “name” y “email” del Model User serán sustituidos por la información publicada por el usuario. Sin embargo, para que esto sea posible, es necesario que dejemos explícito en nuestro Model que estas propiedades pueden ser editadas. Para ello, usamos una propiedad llamada $fillable, que traducido significa “rellenable”.
El Model User, creado por defecto por Laravel, ya tiene esta propiedad, que por coincidencia ya contiene los atributos “name” y “email” definidos. Por lo tanto, no necesitamos preocuparnos por esta configuración:
El método de nuestro Controller ya está listo. Vamos a llamarlo en nuestro archivo de rutas. Para editar los datos de un usuario, podemos elegir entre usar los métodos PUT o PATCH. El primero tiene como objetivo editar todos los datos de un usuario específico. El segundo edita solo parte de los datos de nuestro usuario y será este último el que elegiremos. Nuestro archivo quedará así:
Route::patch('users/{user}', "UsersController@update");
Note que informamos la palabra “user” entre llaves para la ruta. Esto constituye un parámetro para nuestra ruta de edición. Este parámetro será el ID del usuario que deseamos editar. El propio Laravel cargará su información y las editará.
Vamos a crear una nueva solicitud en Insomnia, llamada “Hcode API PATCH”:
Vamos a informar la URL de nuestra API para esta solicitud, definiendo el ID 3 como el que será editado, junto con la información que queremos actualizar:
Al hacer clic en “Send”, vemos el siguiente resultado:
¡Nuestros datos fueron actualizados con éxito!
Eliminando un usuario
Finalmente, vamos a programar la eliminación de un usuario. Crearemos un método llamado remove() en nuestro Controller. Este esperará como parámetro solo los datos del usuario que vamos a eliminar, que será representado por el Model User. Luego, llamaremos al método delete() que esta clase posee. Su código será el siguiente:
public function remove(User $user) {
$user->delete();
return response()->json([
'message'=>'Usuario eliminado con éxito'
]);
}
Vamos a hacer la llamada a este método en nuestro archivo de rutas, usando el método delete():
Route::delete('users/{user}', "UsersController@remove");
Ten en cuenta que en este caso también hicimos uso del paso de parámetros para la ruta.
Vamos a crear la solicitud de eliminación en Insomnia con el nombre “Hcode API DELETE”:
Vamos a definir la URL de la API en nuestra solicitud, informando el ID 1 para ella.
Veremos el siguiente resultado al enviarla:
Nuestro usuario fue eliminado exitosamente.
Es interesante notar que construimos un CRUD de usuarios sin casi acceder a la Base de Datos. Laravel hizo eso por nosotros. De esta forma, si deseáramos manipular otra Base de Datos que no fuera Postgres, solo necesitaríamos cambiar las configuraciones de acceso a ella que definimos en el archivo .env y el código seguiría funcionando.
Puedes encontrar los códigos desarrollados en este artículo en nuestro GitHub.
Laravel es realmente una “mano en la rueda” para crear APIs en PHP de una manera mucho más rápida y simple. Enseñamos otros recursos de este increíble framework en nuestro curso Creando REST API con Laravel 5.7.
Gracias por haber leído y hasta el próximo artículo :)