REST API with Lumen 5.5

A RESTful API boilerplate for Lumen micro-framework. Features included:

Users Resource
OAuth2 Authentication using Laravel Passport
Scope based Authorization
Validation
Repository Pattern
API Response with Fractal
Pagination
Seeding Database With Model Factory
Event Handling
Sending Mail using Mailable class
CORS Support
Rate Limit API Requests
Endpoint Tests and Unit Tests
Build Process with Travis CI

Getting Started

First, clone the repo:

$ git clone [email protected]:hasib32/rest-api-with-lumen.git

Laravel Homestead

You can use Laravel Homestead globally or per project for local development. Follow the Installation Guide.

Install dependencies

$ cd rest-api-with-lumen
$ composer install

Configure the Environment

Create .env file:

$ cat .env.example > .env

If you want you can edit database name, database username and database password.

Migrations and Seed the database with fake data

First, we need connect to the database. For homestead user, login using default homestead username and password:

$ mysql -uhomestead -psecret

Then create a database:

mysql> CREATE DATABASE restapi;

And also create test database:

mysql> CREATE DATABASE restapi_test;

Run the Artisan migrate command with seed:

$ php artisan migrate --seed

Create "personal access" and "password grant" clients which will be used to generate access tokens:

$ php artisan passport:install

You can find those clients in oauth_clients table.

API Routes

HTTP Method	Path	Action	Scope	Desciption
GET	/users	index	users:list	Get all users
POST	/users	store	users:create	Create an user
GET	/users/{user_id}	show	users:read	Fetch an user by id
PUT	/users/{user_id}	update	users:write	Update an user by id
DELETE	/users/{user_id}	destroy	users:delete	Delete an user by id

Note: users/me is a special route for getting current authenticated user. And for all User routes 'users' scope is available if you want to perform all actions.

OAuth2 Routes

Visit dusterio/lumen-passport to see all the available OAuth2 routes.

Creating access_token

Since Laravel Passport doesn't restrict any user creating any valid scope. I had to create a route and controller to restrict user creating access token only with permitted scopes. For creating access_token we have to use the accessToken route. Here is an example of creating access_token for grant_type password with Postman.

http://stackoverflow.com/questions/39436509/laravel-passport-scopes

Creating a New Resource

Creating a new resource is very easy and straight-forward. Follow these simple steps to create a new resource.

Step 1: Create Route

Create a new route name messages. Open the routes/web.php file and add the following code:

$route->post('messages', [
    'uses'       => 'MessageController@store',
    'middleware' => "scope:messages,messages:create"
]);
$route->get('messages',  [
    'uses'       => 'MessageController@index',
    'middleware' => "scope:messages,messages:list"
]);
$route->get('messages/{id}', [
    'uses'       => 'MessageController@show',
    'middleware' => "scope:messages,messages:read"
]);
$route->put('messages/{id}', [
    'uses'       => 'MessageController@update',
    'middleware' => "scope:messages,messages:write"
]);
$route->delete('messages/{id}', [
    'uses'       => 'MessageController@destroy',
    'middleware' => "scope:messages,messages:delete"
]);

For more info please visit Lumen Routing page.

Step 2: Create Model and Migration for the Table

Create Message Model inside App/Models directory and create migration using Lumen Artisan command.

Message Model

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Message extends Model
{
    /**
     * The database table used by the model.
     *
     * @var string
     */
    protected $table = 'messages';

    /**
     * The attributes that are mass assignable.
     *
     * @var array
     */
    protected $fillable = [
        'uid',
        'userId',
        'subject',
        'message',
    ];
}

Visit Laravel Eloquent Page for more info about Model.

Create migration for messages table

php artisan make:migration create_messages_table --create=messages

Migration file

class CreateMessagesTable extends Migration
{
    public function up()
    {
        Schema::create('messages', function (Blueprint $table) {
            $table->increments('id');
            $table->string('uid', 36)->unique();
            $table->integer('userId')->unsigned();
            $table->string('subject')->nullable();
            $table->longText('message');
            $table->timestamps();

            $table->foreign('userId')
                ->references('id')->on('users')
                ->onDelete('cascade')
                ->onUpdate('cascade');
        });
    }
}

For more info visit Laravel Migration page.

Step 3: Create Repository

Create MessageRepository and implementation of the repository name EloquentMessageRepository.

MessageRepository

<?php

namespace App\Repositories\Contracts;

interface MessageRepository extends BaseRepository
{
}

EloquentMessageRepository

<?php

namespace App\Repositories;

use App\Models\Message;
use App\Repositories\Contracts\MessageRepository;

class EloquentMessageRepository extends AbstractEloquentRepository implements MessageRepository
{
    /**
     * Model name.
     *
     * @var string
     */
    protected $modelName = Message::class;
}

Next, update RepositoriesServiceProvider to bind the implementation:

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Repositories\Contracts\UserRepository;
use App\Repositories\EloquentUserRepository;
use App\Repositories\Contracts\MessageRepository;
use App\Repositories\EloquentMessageRepository;

class RepositoriesServiceProvider extends ServiceProvider
{
    /**
     * Indicates if loading of the provider is deferred.
     *
     * @var bool
     */
    protected $defer = true;

    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        $this->app->bind(UserRepository::class, function () {
            return new EloquentUserRepository(new User());
        });
        $this->app->bind(MessageRepository::class, function () {
            return new EloquentMessageRepository(new Message());
        });
    }

    /**
     * Get the services provided by the provider.
     *
     * @return array
     */
    public function provides()
    {
        return [
            UserRepository::class,
            MessageRepository::class,
        ];
    }
}

Visit Lumen documentation for more info about Service Provider.

Step 4: Create Fractal Transformer

Fractal provides a presentation and transformation layer for complex data output, the like found in RESTful APIs, and works really well with JSON. Think of this as a view layer for your JSON/YAML/etc.

Create a new Transformer name MessageTransformer inside app/Transformers directory:

<?php

namespace App\Transformers;

use App\Models\Message;
use League\Fractal\TransformerAbstract;

class MessageTransformer extends TransformerAbstract
{
    public function transform(Message $message)
    {
        return [
            'id'        => $message->uid,
            'userId'    => $message->userId,
            'subject'   => $message->subject,
            'message'   => $message->message,
            'createdAt' => (string) $message->created_at,
            'updatedAt' => (string) $message->updated_at,
        ];
    }
}

Visit Fractal official page for more information.

Step 5: Create Policy

For authorization we need to create policy that way basic user can't show or edit other user messages.

MessagePolicy

<?php

namespace App\Policies;

use App\Models\User;
use App\Models\Message;

class MessagePolicy
{
    /**
     * Intercept checks.
     *
     * @param User $currentUser
     * @return bool
     */
    public function before(User $currentUser)
    {
        if ($currentUser->isAdmin() && (!$currentUser->tokenCan('basic') || $currentUser->tokenCan('undefined'))) {
            return true;
        }
    }

    /**
     * Determine if a given user has permission to show.
     *
     * @param User $currentUser
     * @param Message $message
     * @return bool
     */
    public function show(User $currentUser, Message $message)
    {
        return $currentUser->id === $message->userId;
    }

    /**
     * Determine if a given user can update.
     *
     * @param User $currentUser
     * @param Message $message
     * @return bool
     */
    public function update(User $currentUser, Message $message)
    {
        return $currentUser->id === $message->userId;
    }

    /**
     * Determine if a given user can delete.
     *
     * @param User $currentUser
     * @param Message $message
     * @return bool
     */
    public function destroy(User $currentUser, Message $message)
    {
        return $currentUser->id === $message->userId;
    }
}

Next, update AuthServiceProvider to use the policy:

Gate::policy(Message::class, MessagePolicy::class);

And add scopes to Passport::tokensCan:

[
    'messages' => 'Messages scope',
    'messages:list' => 'Messages scope',
    'messages:read' => 'Messages scope for reading records',
    'messages:write' => 'Messages scope for writing records',
    'messages:create' => 'Messages scope for creating records',
    'messages:delete' => 'Messages scope for deleting records'
]

Visit Lumen Authorization Page for more info about Policy.

Last Step: Create Controller

Finally, let's create the MessageController. Here we're using MessageRepository, MessageTransformer and MessagePolicy.

<?php

namespace App\Http\Controllers;

use App\Models\Message;
use App\Repositories\Contracts\MessageRepository;
use Illuminate\Http\Request;
use App\Transformers\MessageTransformer;

class MessageController extends Controller
{
    /**
     * Instance of MessageRepository.
     *
     * @var MessageRepository
     */
    private $messageRepository;

    /**
     * Instanceof MessageTransformer.
     *
     * @var MessageTransformer
     */
    private $messageTransformer;

    /**
     * Constructor.
     *
     * @param MessageRepository $messageRepository
     * @param MessageTransformer $messageTransformer
     */
    public function __construct(MessageRepository $messageRepository, MessageTransformer $messageTransformer)
    {
        $this->messageRepository = $messageRepository;
        $this->messageTransformer = $messageTransformer;

        parent::__construct();
    }

    /**
     * Display a listing of the resource.
     *
     * @param Request $request
     * @return \Illuminate\Http\JsonResponse
     */
    public function index(Request $request)
    {
        $messages = $this->messageRepository->findBy($request->all());

        return $this->respondWithCollection($messages, $this->messageTransformer);
    }

    /**
     * Display the specified resource.
     *
     * @param $id
     * @return \Illuminate\Http\JsonResponse|string
     */
    public function show($id)
    {
        $message = $this->messageRepository->findOne($id);

        if (!$message instanceof Message) {
            return $this->sendNotFoundResponse("The message with id {$id} doesn't exist");
        }

        // Authorization
        $this->authorize('show', $message);

        return $this->respondWithItem($message, $this->messageTransformer);
    }

    /**
     * Store a newly created resource in storage.
     *
     * @param Request $request
     * @return \Illuminate\Http\JsonResponse|string
     */
    public function store(Request $request)
    {
        // Validation
        $validatorResponse = $this->validateRequest($request, $this->storeRequestValidationRules($request));

        // Send failed response if validation fails
        if ($validatorResponse !== true) {
            return $this->sendInvalidFieldResponse($validatorResponse);
        }

        $message = $this->messageRepository->save($request->all());

        if (!$message instanceof Message) {
            return $this->sendCustomResponse(500, 'Error occurred on creating Message');
        }

        return $this->setStatusCode(201)->respondWithItem($message, $this->messageTransformer);
    }

    /**
     * Update the specified resource in storage.
     *
     * @param Request $request
     * @param $id
     * @return \Illuminate\Http\JsonResponse
     */
    public function update(Request $request, $id)
    {
        // Validation
        $validatorResponse = $this->validateRequest($request, $this->updateRequestValidationRules($request));

        // Send failed response if validation fails
        if ($validatorResponse !== true) {
            return $this->sendInvalidFieldResponse($validatorResponse);
        }

        $message = $this->messageRepository->findOne($id);

        if (!$message instanceof Message) {
            return $this->sendNotFoundResponse("The message with id {$id} doesn't exist");
        }

        // Authorization
        $this->authorize('update', $message);


        $message = $this->messageRepository->update($message, $request->all());

        return $this->respondWithItem($message, $this->messageTransformer);
    }

    /**
     * Remove the specified resource from storage.
     *
     * @param $id
     * @return \Illuminate\Http\JsonResponse|string
     */
    public function destroy($id)
    {
        $message = $this->messageRepository->findOne($id);

        if (!$message instanceof Message) {
            return $this->sendNotFoundResponse("The message with id {$id} doesn't exist");
        }

        // Authorization
        $this->authorize('destroy', $message);

        $this->messageRepository->delete($message);

        return response()->json(null, 204);
    }

    /**
     * Store Request Validation Rules
     *
     * @param Request $request
     * @return array
     */
    private function storeRequestValidationRules(Request $request)
    {
       return [
           'userId'     => 'required|exists:users,id',
           'subject'    => 'required',
           'message'    => 'required',
        ];
    }

    /**
     * Update Request validation Rules
     *
     * @param Request $request
     * @return array
     */
    private function updateRequestValidationRules(Request $request)
    {
        return [
            'subject'    => '',
            'message'    => '',
        ];
    }
}

Visit Lumen Controller page for more info about Controller.

Tutorial

To see the step-by-step tutorial how I created this boilerplate please visit our blog devnootes.net.

Contributing

Contributions, questions and comments are all welcome and encouraged. For code contributions submit a pull request.

Credits

Taylor Otwell, Shahriar Mahmood, Fractal, Phil Sturgeon

License

MIT license

Invalid Credentials

I am running your tutorial, but I could not get the accessToken. This is the response that I received. I am trying with severals of emails registered in the database (fake data) with the password: test-password but i am getting this response

{ "error": "invalid_credentials", "message": "The user credentials were incorrect." }

opened by jossydeleon 15
Upgrade to lumen 5.5

Hi,

The project looks interesting. I'm going to use it for one project, but I'm not sure if I need to use the previous version. Do you have any plans to upgrade it to 5.5? Should I wait or can start using current version.

Thanks in advance.

opened by vbezruchkin 11
Issue to create access Token

Hello,

first of all a lot of thanks for the tuto on devops ans this repo git; I'm trying to get an access Token with postman:

If i'm right, something missing in the "headers" section. And i choose client_id "2", in reference at the table "oauth_clients" for "Password Grant Client".

What am i do wrong? Could you please help me?

Regards

opened by LordLightAngels 9
[NEED HELP] "Insufficient privileges to perform this action", other than users:list
I've got the response ("Insufficient privileges to perform this action") towards the api_token when try to register or login. i don't know what went wrong register method: https://pastebin.com/Wn2YVTKs login method: https://pastebin.com/bCDScg7B I've had:

migrate and seed

passport:install

register or login and accessing UserController@show,update,destroy by passing the retrieved token

An example accessing UserController@show, got error:

Note: UserController@store hasn't tested yet

Update: when I comment the this->authorize() for each given methods, it works. means there's something wrong in the policy. what should I do next?
opened by handhikadj 8
Getting 404 on every request

First of all thanks for putting this boilerplate together.

I've gone through the setup guide but I keep getting 404's on every request. I'm not running the project using homestead, instead I want to be able to just go to http://localhost/project-name/public but this returns a 404.

Am I missing a step? Any help is greatly appreciated.

opened by pattle 7
No getting information

After getting the accessToken without any problem, how can I get another information from API. For example I trying to get the information of current user doing this:

But I am getting this when I use http://localhost/users/me:

{ "status": 405, "message": "Method Not Allowed" }

http://localhost/users

{ "status": 401, "message": "Unauthorized" } Also If I want to save new user or update. If someone has done this, can you share it. Thank you

opened by limaho 5
Show how scopes are difened

Based on my issue for scopes #31 this is my pull request. You have basic 'users' scope for all user related stuff. And users:create, users:read..etc. if you want specific scope for a token. For Administrator there is no logic to have 'admin' scope, so if you pass and 'basic' scope to an administrator he will have the same permissions as a nomer users and he will be able to control only his objects. I also updated the Readme file for message entity. If you find any problem please let me know or if you don't agree with my proposal.

opened by ibpavlov 3
Set model for Repositories from the constructor.

This pull request is based on the issue here

I've added a parameter in the repository constructor to be able to pass a child of the base model. I've run all tests before this commit and they all passed. Also, I've updated Readme guides.

opened by ibpavlov 3
update readme

update app\Providers\RepositoriesServiceProvider.php :

use App\Repositories\Contracts\MessageRepository; use App\Repositories\EloquentMessageRepository;

opened by dev-chriss 3
$Target [Illuminate\Contracts\Http\Kernel] is not instantiable.$

Target [Illuminate\Contracts\Http\Kernel] is not instantiable.

After cloning repo. when i try to run

php artisan migrate

i am getting following error

[Illuminate\Contracts\Container\BindingResolutionException] Target [Illuminate\Contracts\Http\Kernel] is not instantiable.

php : 7.0.23

opened by ShayanSolution 2
understanding the use of the accesstokencontroller

hello i have a issue with the accesstoken controller

as far i can understand we are using the token for accesstokencontroller as the token for the entire application right

that is my login or im missing the point ?

opened by zeruel01 2
How to call event in new Lumen

In /app/Repositories/EloquentUserRepository.php

The correct use of Event in Laravel/Lumen is:

\Event::fire(new UserCreatedEvent($user));

or

event(new UserCreatedEvent($user));

And my IDE dont know who is \Event in the first case (PhpStorm)

opened by gfernandez-me 0
Private/Public Key exchange

Hi @hasib32

First of all I would thank you for this boilerplate really awesome.

Quick Question can you please pont me to the right directions how I can implement the private/public key exchange on your boilerplate? I have very limited info regarding this.

Thanks.

opened by kabelo38 1