ApiGuard

A simple way of authenticating your APIs with API keys using Laravel. This package uses the following libraries:

• philsturgeon's Fractal
• maximebeaudoin's api-response

The concept for managing API keys is also taken from Phil Sturgeon's codeigniter-restserver. I've been looking for an equivalent for Laravel but did not find any so this is an implementation for that.

**Laravel 5.1.x to 5.2.x: ~3.*

**Laravel 5.1.x: ~2.*

**Laravel 4.2.x: ~1.* (Recently updated version for Laravel 4. Please note that there are namespace changes here)

**Laravel 4.2.x: 0.* (The version that most of you are using)

Run composer require chrisbjr/api-guard 3.1.*

In your config/app.php add Chrisbjr\ApiGuard\Providers\ApiGuardServiceProvider to the end of the providers array

'providers' => array(

    ...
    Chrisbjr\ApiGuard\Providers\ApiGuardServiceProvider::class,
),

Add the ApiGuardAuth facade to the end of the aliases array as well

'aliases' => array(

    ...
    'ApiGuardAuth' => \Chrisbjr\ApiGuard\Facades\ApiGuardAuth::class,
),

Add the following middleware inside your app/Http/Kernel.php file:

protected $routeMiddleware = [
    ...
    'apiguard' => \Chrisbjr\ApiGuard\Http\Middleware\ApiGuard::class,
];

Now publish the migration and configuration files for api-guard:

$ php artisan vendor:publish --provider="Chrisbjr\ApiGuard\Providers\ApiGuardServiceProvider"

Then run the migration:

$ php artisan migrate

It will setup two tables - api_keys and api_logs.

Note: Documentation for use with Laravel 5.0.x and 5.1.x differs from Laravel 5.2.x. Please refer to the README here.

Note: Documentation for use with Laravel 4.2.x differs from Laravel 5.0.x. Please refer to the README here. If you are using version 0.* you can find the README here

Once you're done with the required setup, you can now generate your first API key.

Run the following command to generate an API key:

php artisan api-key:generate

Generally, you will want to generate API keys for each user in your application. The api_keys table has a user_id field which you can populate for your users.

To generate an API key that is linked to a user, you can do the following:

php artisan api-key:generate --user-id=1

To generate an API key from within your application, you can use the following method in the ApiKey model:

$apiKey = Chrisbjr\ApiGuard\Models\ApiKey::make()

Basic usage of ApiGuard is to create a controller and extend that class to use the ApiGuardController.

Note: The namespace of the ApiGuardController differs from previous versions.

<?php

use Chrisbjr\ApiGuard\Http\Controllers\ApiGuardController;

class BooksController extends ApiGuardController
{

    public function all()
    {
        $books = Book::all();

        return $this->response->withCollection($books, new BookTransformer);
    }
    
    public function show($id)
    {
        try {
        
            $book = Book::findOrFail($id);
            
            return $this->response->withItem($book, new BookTransformer);
            
        } catch (ModelNotFoundException $e) {
        
            return $this->response->errorNotFound();
            
        }
    }

}

You should be able to use the api-response object by using $this->response. More examples can be found on the Github page: https://github.com/ellipsesynergie/api-response.

You can access the above controller by creating a basic route in your app/routes.php:

Route::get('api/v1/books', 'BooksController@all');
Route::get('api/v1/books/{id}', 'BooksController@show');

You will need to use your API key and put it in the header to access it. By default, the header value is using the X-Authorization parameter. You can change this in the config file.

Try calling this route using curl

curl --header "X-Authorization: 2ed9d72e5596800bf805ca1c735e446df72019ef" http://localhost:8000/api/v1/books

You should get the following response:

{
    "data": {
        "id": 1,
        "title": "The Great Adventures of Chris",
        "created_at": {
            "date": "2014-03-25 18:54:18",
            "timezone_type": 3,
            "timezone": "UTC"
        },
        "updated_at": {
            "date": "2014-03-25 18:54:18",
            "timezone_type": 3,
            "timezone": "UTC"
        },
        "deleted_at": null
    }
}

There are various options that can be specified for each method in your controller. These options can be specified inside the $apiMethods variable. Examples can be found below.

By default, all the methods in the ApiGuardController will be authenticated. To turn this off for a specific method, use the keyAuthentication option.

<?php

use Chrisbjr\ApiGuard\Http\Controllers\ApiGuardController;

class BooksController extends ApiGuardController
{

    protected $apiMethods = [
        'show' => [
            'keyAuthentication' => false
        ],
    ];

    ...

}

This above example will turn off key authentication for the show method.

If you take a look at the api_keys table in your database, you will notice that there is a level field.

This will allow you to specify a level for your API key and if the method has a higher level than the API key, access will be restricted. Here is an example on how to set the level on a method:

<?php

use Chrisbjr\ApiGuard\Http\Controllers\ApiGuardController;

class BooksController extends ApiGuardController
{

    protected $apiMethods = [
        'show' => [
            'level' => 10
        ],
    ];
    
    ...

}

Now if your API key has a level of 9 or lower, then access to the show method will be restricted.

You can limit the rate at which an API key can have access to a particular method by using the limits.key option.

<?php

use Chrisbjr\ApiGuard\Http\Controllers\ApiGuardController;

class BooksController extends ApiGuardController
{

    protected $apiMethods = [
        'show' => [
            'limits' => [
                'key' => [
                    'increment' => '1 hour',
                    'limit' => 100
                ]
            ]
        ],
    ];
    
    ...

}

The above example will limit the access to the show method of an API key to 100 requests for every hour.

Note: The increment option can be any value that is accepted by the strtotime() method.

There is also an option to limit the request rate for a given method no matter what API key is used. For this, we use the limits.method option.

<?php

use Chrisbjr\ApiGuard\Http\Controllers\ApiGuardController;

class BooksController extends ApiGuardController
{

    protected $apiMethods = [
        'show' => [
            'limits' => [
                'method' => [
                    'increment' => '1 day',
                    'limit' => 1000
                ]
            ]
        ],
    ];
    
    ...

}

The above example will limit the request rate to the show method to 1000 requests per day.

Note: The increment option can be any value that is accepted by the strtotime() method.

You can set logging at method level by using the logged option.

<?php

use Chrisbjr\ApiGuard\Http\Controllers\ApiGuardController;

class BooksController extends ApiGuardController
{

    protected $apiMethods = [
        'show' => [
            'logged' => true
        ]
    ];
    
    ...

}

By default for all methods in api-guard, the option logged is set to true. Set it to false to exclude that method for logging.