Restful API Tutorial With Lumen Laravel 5.5 For Beginners

Lumen is the best PHP framework to build the Restful API. Lumen was developed by Taylor Otwell, the developer behind the most popular PHP framework today, Laravel. You could say, Lumen is a derivative of Laravel. The following tutorial will discuss what Lumen and the tutorial create a restful API using Lumen 5.5.

If previously I discussed the article about the Slim framework, Lumen has the same goal, which is a micro-framework tasked to build APIs easily, quickly and efficiently. Besides, Lumen can handle 1900 requests per second like the picture below.

The advantages of Lumen framework itself in my experience are:

Many features such as middleware authentication.
Strong MVC concept.
Migrate and eloquent features that speed up the creation and query of databases

Many people say that Laravel is a heavy PHP framework, but Lumen is created with speed and simplify of the features in Laravel. In this article, we will prove how quickly and easily make the API use Lumen Framework.

Another tutorial : How To Load All Data Before Rendering View Component In Angular 4

Prepare to create a web API with lumen 5.5

System Requirement

Before starting the creation of the API, there are some requirements that must be fulfilled, so that Lumen framework 5.5 runs well on the server

PHP 7.0
OpenSSL PHP Extension
PDO PHP Extension
Mbstring PHP Extension

Installation

To install Lumen is quite easy, using a composer you just need to run the following script

composer create-project --prefer-dist laravel/lumen lumenapi

1	composer create-project --prefer-dist laravel/lumen lumenapi

Configuration

Before running Lumen, there are some configurations in the .env file that must be adjusted. Open the .env file, while the default file is as follows.

APP_ENV=local
APP_DEBUG=true
APP_KEY=VUEdpbKOpVlP4817
APP_TIMEZONE=Asia/Jakarta

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your-db-name
DB_USERNAME=your-db-user
DB_PASSWORD=your-db-password

CACHE_DRIVER=file
QUEUE_DRIVER=sync

APP_ENV=local

APP_DEBUG=true

APP_KEY=VUEdpbKOpVlP4817

APP_TIMEZONE=Asia/Jakarta

DB_CONNECTION=mysql

DB_HOST=127.0.0.1

DB_PORT=3306

DB_DATABASE=your-db-name

DB_USERNAME=your-db-user

DB_PASSWORD=your-db-password

CACHE_DRIVER=file

QUEUE_DRIVER=sync

Unlike Laravel, APP_KEY has not filled automatically. You can fill APP_KEY manually.

Then the APP_TIMEZONE option. Adjust to the time zone of application used. I am as an Indonesian developer using timezone “Asia/Jakarta.” You can see the timezone list here.

Lumen Early Installation Test

Lumen does not provide tools to run a built-in web server like Laravel (PHP artisan serve). We can use the built-in web server directly with PHP.

$ PHP -S localhost:8888 -t public

1	$ PHP -S localhost:8888 -t public

or you can copy the entire Lumen project into the HTML (/var/www/html/) or htdocs folder (inside the XAMPP folder) and run it as usual.

http://ipaddress/lumenproject/public/

1	http://ipaddress/lumenproject/public/

Till this step, the preparation of the Web API using the Lumen 5.5 framework has been completed. The next step we will create a simple REST API Lumen where the API server is used for new user registration, login application and get API_TOKEN to retrieve user data using token authentication.

Creating a Simple REST API Using the Lumen 5.5 Framework For Beginners

Please edit the boostrap / app.php file. Here we will activate the auth and eloquent feature. Eliminate some comments like the following:

$app->withFacades();
$app->withEloquent();
$app->routeMiddleware([
    'auth' => App\Http\Middleware\Authenticate::class,
]);
$app->register(App\Providers\AuthServiceProvider::class);

$app->withFacades();

$app->withEloquent();

$app->routeMiddleware([

'auth' => App\Http\Middleware\Authenticate::class,

]);

$app->register(App\Providers\AuthServiceProvider::class);

By default the Facades and Eloquent features are removed so that Lumen can work faster.

Migration Lumen

Database migration is one of the features to create database schema quickly and easily. For the simple application of REST API, we will create schema table for the user.

php artisan make:migration create_users_table --create=users

1	php artisan make:migration create_users_table --create=users

Make sure the file is formed like the following image in the folder database/migrations/

Edit the above file and add the following schema:

<?php

use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class CreateUsersTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('users', function (Blueprint $table) {
            $table->increments('id');
            $table->string('username');
            $table->string('email')->unique();
            $table->string('password');
            $table->string('api_token');
            $table->rememberToken();
            $table->timestamps();
            $table->softDeletes();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::dropIfExists('users');
    }
}

<?php

use Illuminate\Support\Facades\Schema;

use Illuminate\Database\Schema\Blueprint;

use Illuminate\Database\Migrations\Migration;

class CreateUsersTable extends Migration

{

/**

* Run the migrations.

* @return void

public function up()

{

Schema::create('users', function (Blueprint $table) {

$table->increments('id');

$table->string('username');

$table->string('email')->unique();

$table->string('password');

$table->string('api_token');

$table->rememberToken();

$table->timestamps();

$table->softDeletes();

});

}

/**

* Reverse the migrations.

* @return void

public function down()

{

Schema::dropIfExists('users');

}

When done, migrate with the following command:

php artisan migrate

1	php artisan migrate

Check your database through phpmyadmin and see if the users table has been established?

Creating a Model of the Lumen 5.5 Framework

After creating the migration automatically, then the model for the user has been formed in the folder /app/User.php. To understand more about the model, please read at https://laravel.com/docs/5.5/eloquent. Make sure the User configuration is as follows:

<?php

namespace App;

use Illuminate\Auth\Authenticatable;
use Laravel\Lumen\Auth\Authorizable;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract;
use Illuminate\Contracts\Auth\Access\Authorizable as AuthorizableContract;

class User extends Model implements AuthenticatableContract, AuthorizableContract
{
    use Authenticatable, Authorizable;

    protected $fillable = [
        'username', 'email', 'password', 'api_token'
    ];

    protected $hidden = [
        'password','api_token'
    ];
}

<?php

namespace App;

use Illuminate\Auth\Authenticatable;

use Laravel\Lumen\Auth\Authorizable;

use Illuminate\Database\Eloquent\Model;

use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract;

use Illuminate\Contracts\Auth\Access\Authorizable as AuthorizableContract;

class User extends Model implements AuthenticatableContract, AuthorizableContract

{

use Authenticatable, Authorizable;

protected $fillable = [

'username', 'email', 'password', 'api_token'

];

protected $hidden = [

'password','api_token'

];

}

Explanation:

In Laravel, there are some special variables that are used to configure table settings in the database. As the example above is the variable $fillable , $hidden . And much more like $primaryKey , $timestamps that you can read at https://laravel.com/docs/5.5/eloquent.

$fillable is a variable that serves to grant any column permissions from this users’ table that we can use.

$hidden works to prevent certain fields from being displayed when we query to get all data from columns in database users.

Creating a Controller In Lumen Framework

Unfortunately, php artisan does not provide a feature to make the controller automatically. So we will create the controller manually. The lumen controller is the same as Laravel that works to be used as business logic of the application.

Although lumen does not provide the feature of creating the controller automatically, Lumen provides exampleController.php which can be used as a mock-up to create a new controller.

First of all we will create a UserController located within the folder /app/Http/Controller/ . Please copy the following code and paste it in the UserController.php:

<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;
use App\User;
class UserController extends Controller
{
    public function register(Request $request)
    {
        $rules = [
            'username' => 'required',
            'email' => 'required',
            'password' => 'required',
         ];

        $customMessages = [
             'required' => 'Please fill attribute :attribute'
        ];
        $this->validate($request, $rules, $customMessages);

        try {
            $hasher = app()->make('hash');
            $username = $request->input('username');
            $email = $request->input('email');
            $password = $hasher->make($request->input('password'));

            $save = User::create([
                'username'=> $username,
                'email'=> $email,
                'password'=> $password,
                'api_token'=> ''
            ]);
            $res['status'] = true;
            $res['message'] = 'Registration success!';
            return response($res, 200);
        } catch (\Illuminate\Database\QueryException $ex) {
            $res['status'] = false;
            $res['message'] = $ex->getMessage();
            return response($res, 500);
        }
    }

    public function get_user()
    {
        $user = User::all();
        if ($user) {
              $res['status'] = true;
              $res['message'] = $user;

              return response($res);
        }else{
          $res['status'] = false;
          $res['message'] = 'Cannot find user!';

          return response($res);
        }
    }
}

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

use Illuminate\Validation\ValidationException;

use App\User;

class UserController extends Controller

{

public function register(Request $request)

{

$rules = [

'username' => 'required',

'email' => 'required',

'password' => 'required',

];

$customMessages = [

'required' => 'Please fill attribute :attribute'

];

$this->validate($request, $rules, $customMessages);

try {

$hasher = app()->make('hash');

$username = $request->input('username');

$email = $request->input('email');

$password = $hasher->make($request->input('password'));

$save = User::create([

'username'=> $username,

'email'=> $email,

'password'=> $password,

'api_token'=> ''

]);

$res['status'] = true;

$res['message'] = 'Registration success!';

return response($res, 200);

} catch (\Illuminate\Database\QueryException $ex) {

$res['status'] = false;

$res['message'] = $ex->getMessage();

return response($res, 500);

}

public function get_user()

{

$user = User::all();

if ($user) {

$res['status'] = true;

$res['message'] = $user;

return response($res);

}else{

$res['status'] = false;

$res['message'] = 'Cannot find user!';

return response($res);

}

Add the following code in the Controller.php in the folder /app/Http/Controllers/

<?php

namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;
use Laravel\Lumen\Routing\Controller as BaseController;

class Controller extends BaseController
{
  protected function buildFailedValidationResponse(Request $request, array $errors)
  {
      return response(["success"=> false , "message" => $errors],401);
  }
}

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

use Illuminate\Validation\ValidationException;

use Laravel\Lumen\Routing\Controller as BaseController;

class Controller extends BaseController

{

protected function buildFailedValidationResponse(Request $request, array $errors)

{

return response(["success"=> false , "message" => $errors],401);

}

A brief description:

The above example we will create the registration method in the UserController class. The registration method is used to register the new user.

$rules = [
            'username' => 'required',
            'email' => 'required',
            'password' => 'required',
         ];

        $customMessages = [
             'required' => 'Please fill attribute :attribute'
        ];
        $this->validate($request, $rules, $customMessages);

$rules = [

'username' => 'required',

'email' => 'required',

'password' => 'required',

];

$customMessages = [

'required' => 'Please fill attribute :attribute'

];

$this->validate($request, $rules, $customMessages);

Before the new user is created, Lumen will validate the parameters needed to register the new user.

For Lumen validation to return the json response format, we will inject the buildFailedValidationResponse function in the Controller.php in the /app/Http/Controllers/ folder. The Controller.php file is the parent class of the UserController we have created.

To perform a database query, we need to apply a try catch handle to handle the response if there is an error while querying the database. The try catch template in Lumen like the following code

try { 
// query code here 
} 
catch (\Illuminate\Database\QueryException $ex) 
{ 
//return response if fails here 
}

try {

// query code here

}

catch (\Illuminate\Database\QueryException $ex)

{

//return response if fails here

}

The next step is to create LoginController.php which is used as the login controller. Copy the following code in LoginController.php.

<?php
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;
use Illuminate\Support\Facades\Hash;
use App\User;

class LoginController extends Controller
{
    public function login(Request $request)
    {

      $rules = [
          'email' => 'required',
          'password' => 'required'
      ];

        $customMessages = [
           'required' => ':attribute tidak boleh kosong'
      ];
        $this->validate($request, $rules, $customMessages);
         $email    = $request->input('email');
        try {
            $login = User::where('email', $email)->first();
            if ($login) {
                if ($login->count() > 0) {
                    if (Hash::check($request->input('password'), $login->password)) {
                        try {
                            $api_token = sha1($login->id_user.time());

                              $create_token = User::where('id', $login->id_user)->update(['api_token' => $api_token]);
                              $res['status'] = true;
                              $res['message'] = 'Success login';
                              $res['data'] =  $login;
                              $res['api_token'] =  $api_token;

                              return response($res, 200);


                        } catch (\Illuminate\Database\QueryException $ex) {
                            $res['status'] = false;
                            $res['message'] = $ex->getMessage();
                            return response($res, 500);
                        }
                    } else {
                        $res['success'] = false;
                        $res['message'] = 'Username / email / password not found';
                        return response($res, 401);
                    }
                } else {
                    $res['success'] = false;
                    $res['message'] = 'Username / email / password  not found';
                    return response($res, 401);
                }
            } else {
                $res['success'] = false;
                $res['message'] = 'Username / email / password not found';
                return response($res, 401);
            }
        } catch (\Illuminate\Database\QueryException $ex) {
            $res['success'] = false;
            $res['message'] = $ex->getMessage();
            return response($res, 500);
        }
    }
}

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

use Illuminate\Validation\ValidationException;

use Illuminate\Support\Facades\Hash;

use App\User;

class LoginController extends Controller

{

public function login(Request $request)

{

$rules = [

'email' => 'required',

'password' => 'required'

];

$customMessages = [

'required' => ':attribute tidak boleh kosong'

];

$this->validate($request, $rules, $customMessages);

$email = $request->input('email');

try {

$login = User::where('email', $email)->first();

if ($login) {

if ($login->count() > 0) {

if (Hash::check($request->input('password'), $login->password)) {

try {

$api_token = sha1($login->id_user.time());

$create_token = User::where('id', $login->id_user)->update(['api_token' => $api_token]);

$res['status'] = true;

$res['message'] = 'Success login';

$res['data'] = $login;

$res['api_token'] = $api_token;

return response($res, 200);

} catch (\Illuminate\Database\QueryException $ex) {

$res['status'] = false;

$res['message'] = $ex->getMessage();

return response($res, 500);

}

} else {

$res['success'] = false;

$res['message'] = 'Username / email / password not found';

return response($res, 401);

}

} else {

$res['success'] = false;

$res['message'] = 'Username / email / password not found';

return response($res, 401);

}

} else {

$res['success'] = false;

$res['message'] = 'Username / email / password not found';

return response($res, 401);

}

} catch (\Illuminate\Database\QueryException $ex) {

$res['success'] = false;

$res['message'] = $ex->getMessage();

return response($res, 500);

}

A brief description :

Users will login by email. The server will checks whether the email used for login has been registered in the database or not.

$login = User::where('email', $email)->first();

1	$login = User::where('email', $email)->first();

If it has been registered, Lumen will match whether the password recorded on the database is the same as the password sent by the user using the following function

if (Hash::check($request->input('password'), $login->password))

1	if (Hash::check($request->input('password'), $login->password))

If the login has been successful, the Server will establish a new token to be updated into the database and returned as a response.

Up to this point the tutorial create controller on Lumen API for beginners has been completed. The next stage is the last step where we will make routes that work to handle our request in Url, then direct the application to call the page.

Creating a Lumen Framework Routing

The Route in the Lumen 5.5 framework is located in the folder routes/web.php file. Please copy the following code on web.php:

<?php
$router->get('/', function () use ($router) {
	return $router->app->version();
});
$router->post('/login', 'LoginController@login');
$router->post('/register', 'UserController@register');
$router->get('/user', ['middleware' => 'auth', 'uses' =>  'UserController@get_user']);

<?php

$router->get('/', function () use ($router) {

return $router->app->version();

});

$router->post('/login', 'LoginController@login');

$router->post('/register', 'UserController@register');

$router->get('/user', ['middleware' => 'auth', 'uses' => 'UserController@get_user']);

In the last line the code above the route will use the authenticate middleware used to verify access token from the user. This middleware function is used to deny sources that don’t have access to a particular request

API token validation with Middleware

According to the laravel official website, HTTP middleware is

HTTP middleware provides a convenient mechanism for filtering HTTP requests entering your application

So middleware authentication is a function that runs before this request gets into the controller. Middleware will check whether the user has permission to access the API.

We have enabled Authenticate middleware in the initial configuration above on the bootstrap/app.php file

$app->routeMiddleware([
    'auth' => App\Http\Middleware\Authenticate::class,
]);
$app->register(App\Providers\AuthServiceProvider::class);

$app->routeMiddleware([

'auth' => App\Http\Middleware\Authenticate::class,

]);

$app->register(App\Providers\AuthServiceProvider::class);

Then add the following authentication code inside the authentication middleware that Lumen has prepared in the app/Http/Middleware/Authenticate.php folder

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Contracts\Auth\Factory as Auth;
use App\User;

class Authenticate
{
    protected $auth;
    public function __construct(Auth $auth)
    {
        $this->auth = $auth;
    }
    public function handle($request, Closure $next, $guard = null)
    {
        if ($this->auth->guard($guard)->guest()) {
            if ($request->has('api_token')) {
                try {
                    $token = $request->input('api_token');
                    $check_token = User::where('api_token', $token)->first();
                    if ($check_token) {
                        $res['status'] = false;
                        $res['message'] = 'Unauthorize';
                        return response($res, 401);
                    }
                } catch (\Illuminate\Database\QueryException $ex) {
                    $res['status'] = false;
                    $res['message'] = $ex->getMessage();
                    return response($res, 500);
                }
            } else {
                $res['status'] = false;
                $res['message'] = 'Login please!';
                return response($res, 401);
            }
        }
        return $next($request);
    }
}