Uso questo articolo per segnalare un progetto che ho (ri)portato a termine proprio oggi. Quante volte ci è capitato di dover creare un’API con Laravel? Siamo nel 2016, per cui credo un bel po’ di volte. Ecco, è capitato anche a me. La prima volta ho fatto qualche prova e ho messo su un primo tentativo, poi col tempo l’ho migliorato. Alla fine, dopo svariate iterazioni, ho deciso di condividerlo su Github, a disposizione di tutti.
Cosa ci è uscito fuori? Il Laravel API Boilerplate (JWT Edition)!
In poche parole, questo package permette di mettere su in poco tempo, praticamente al volo, tutto quello che serve per sviluppare delle REST API seguendo svariate buone pratiche. Si tratta fondamentalmente di un’integrazione, in Laravel, di tre ottimi package:
- JWT-Auth – tymondesigns/jwt-auth
- Dingo API – dingo/api
- Laravel-CORS barryvdh/laravel-cors
“Ok, bella, ma non l’avevi già pubblicato? Perchè farci un articolo oggi?”
Perchè, dopo varie richieste, ho trovato un po’ di tempo per aggiornarlo in modo tale da renderlo compatibile con Laravel 5.3.
Non si tratta però soltanto di un cambio di versione del framework: ho preferito prendermi qualche ora in più per riscrivere totalmente tutto il boilerplate, scrivendo i test e poi implementando il codice. Il risultato è quindi uscito fuori più pulito e più stabile.
Vediamo al volo come installarlo, e come usarlo.
Installazione
Una volta predisposto Homestead, o quello che preferisci per sviluppare, tutto quello che devi fare è eseguire il comando
$ composer create-project francescomalatesta/laravel-api-boilerplate-jwt myNextProject
dove ovviamente myNextProject è il nome della cartella in cui verrà creato il nuovo progetto. Una volta terminato il processo, esegui
$ php artisan migrate
per preparare le tabelle necessarie al boilerplate. Nulla di particolare, sono le stesse migration che trovi con Laravel di default!
E… niente, finito.
Autenticazione
Una delle maggiori comodità di questo boilerplate sta nell’aver già predisposto tutto quello che serve all’autenticazione del nostro utente.
In app/Api/V1/Controllers, infatti, trovi già dei controller pronti all’uso, costruiti ad-hoc per gestire l’accesso degli utenti, la registrazione, il recovery delle credenziali ed il successivo reset delle password. Per mantenermi in linea con Laravel 5.3 ho implementato queste quattro funzionalità in altrettanti controller. Guarda tu stesso nel repository.
Route
Per evitare di farti perdere troppo tempo, ho predisposto in routes/api.php una serie di route già pronte ad essere usate, in modo tale da poter percepire subito le varie possibilità offerte dal progetto.
Guardiamo insieme il file:
<!--?php
use DingoApiRoutingRouter;
/** @var Router $api */
$api = app(Router::class);
$api--->version('v1', function (Router $api) {
$api->group(['prefix' => 'auth'], function(Router $api) {
$api->post('signup', 'SignUpController@signUp');
$api->post('login', 'LoginController@login');
$api->post('recovery', 'ForgotPasswordController@sendResetEmail');
$api->post('reset', 'ResetPasswordController@resetPassword');
});
$api->group(['middleware' => 'jwt.auth'], function(Router $api) {
$api->get('protected', function() {
return response()->json([
'message' => 'Access to this item is only for authenticated user. Provide a token in your request!'
]);
});
$api->get('refresh', [
'middleware' => 'jwt.refresh',
function() {
return response()->json([
'message' => 'By accessing this endpoint, you can refresh your access token at each request. Check out this response headers!'
]);
}
]);
});
$api->get('hello', function() {
return response()->json([
'message' => 'This is a simple example of item returned by your APIs. Everyone can see it.'
]);
});
});
Piuttosto semplice: la route hello è pubblica. Tutti la possono leggere in qualsiasi momento.
Poco più in alto, invece, viene creato un gruppo che condivide il middleware jwt.auth. Le route qui sotto faranno uso di questo middleware, che si occupa di verificare la presenza di un access token nella richiesta.
In questo gruppo c’è la route refresh, che oltre ad essere “protetta” dal middleware jwt.auth fa uso anche dell’altro middleware messo a disposizione da JWT-Auth, jwt.refresh, che restituisce un nuovo token al client ad ogni richiesta. Un ulteriore livello di sicurezza!
… ed ora?
Hai una buona base di partenza per il tuo prossimo progetto. Fammi sapere che ne pensi, e se trovi un bug apri una issue su Github!
E quando vuoi, sei il benvenuto sul nostro Slack!
