README

使用 Laravel 通过 API 密钥简单验证你的 API。本包使用了以下库

philsturgeon 的 Fractal
maximebeaudoin 的 api-response

API 密钥管理的概念也借鉴了 Phil Sturgeon 的 codeigniter-restserver。我在寻找 Laravel 的等效方案，但没有找到，所以这是为 Laravel 实现的一个方案。

已修复以支持 LARAVEL 5.3.*

Laravel 5 终于支持了！

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

**Laravel 5.1.x: ~2.*

**Laravel 4.2.x: ~1.*（最近更新版本的 Laravel 4。请注意这里有一些命名空间的变化）

**Laravel 4.2.x: 0.*（大多数人都使用的版本）

快速开始

Laravel 5.1.x 到 5.2.x

运行 composer require chrisbjr/api-guard 3.1.*

在你的 config/app.php 中，将 Chrisbjr\ApiGuard\Providers\ApiGuardServiceProvider 添加到 providers 数组的末尾

'providers' => array(

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

同时，将 ApiGuardAuth 门面添加到 aliases 数组的末尾

'aliases' => array(

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

在你的 app/Http/Kernel.php 文件中添加以下中间件

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

现在发布 api-guard 的迁移和配置文件

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

然后运行迁移

$ php artisan migrate

它将设置两个表 - api_keys 和 api_logs。

Laravel 5.0.x 到 5.1.x（旧用户）

注意：用于 Laravel 5.0.x 和 5.1.x 的文档与 Laravel 5.2.x 不同。请参阅此处的 README。

Laravel 4.2.x

注意：用于 Laravel 4.2.x 的文档与 Laravel 5.0.x 不同。请参阅此处的 README。如果你使用的是版本 0.*，你可以在此处找到 README。

生成第一个 API 密钥

完成必要的设置后，你现在可以生成第一个 API 密钥。

运行以下命令来生成 API 密钥

php artisan api-key:generate

通常，你希望为应用程序中的每个用户生成 API 密钥。在 api_keys 表中有一个 user_id 字段，你可以为你的用户填充。

要生成与用户关联的 API 密钥，你可以这样做

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

要从应用程序内部生成 API 密钥，你可以在 ApiKey 模型中使用以下方法

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

用法

ApiGuard 的基本用法是创建一个控制器并扩展该类以使用 ApiGuardController。

注意：与先前版本相比，ApiGuardController 的命名空间有所不同。

<?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();
            
        }
    }

}

您应该可以使用 $this->response 来使用 api-response 对象。更多示例可以在 Github 页面上找到：[https://github.com/ellipsesynergie/api-response](https://github.com/ellipsesynergie/api-response)。

您可以在 app/routes.php 中创建基本路由来访问上述控制器。

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

您需要使用您的 API 密钥并将其放入头信息中才能访问它。默认情况下，头信息值使用 X-Authorization 参数。您可以在配置文件中更改此设置。

尝试使用 curl 调用此路由

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

您应该得到以下响应

{
    "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
    }
}

API 选项

您可以为控制器中的每个方法指定各种选项。这些选项可以在 $apiMethods 变量中指定。下面有一些示例。

关闭特定方法的 API 密钥认证

默认情况下，ApiGuardController 中的所有方法都将进行认证。要关闭特定方法的认证，请使用 keyAuthentication 选项。

<?php

use Chrisbjr\ApiGuard\Http\Controllers\ApiGuardController;

class BooksController extends ApiGuardController
{

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

    ...

}

上面的示例将关闭 show 方法的密钥认证。

指定 API 方法的访问级别

如果您查看数据库中的 api_keys 表，您会注意到有一个 level 字段。

这将允许您为 API 密钥指定一个级别，并且如果方法级别高于 API 密钥，则访问将被限制。以下是如何在方法上设置级别的示例

<?php

use Chrisbjr\ApiGuard\Http\Controllers\ApiGuardController;

class BooksController extends ApiGuardController
{

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

}

现在，如果您的 API 密钥级别为 9 或以下，则对 show 方法的访问将被限制。

限制 API 密钥的访问速率

您可以使用 limits.key 选项来限制 API 密钥对特定方法的访问速率。

<?php

use Chrisbjr\ApiGuard\Http\Controllers\ApiGuardController;

class BooksController extends ApiGuardController
{

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

}

上面的示例将限制 API 密钥对 show 方法的访问为每小时 100 请求。

注意：increment 选项可以是 strtotime() 方法接受的任何值。

限制对方法的访问

还有一个选项可以限制无论使用什么 API 密钥，给定方法的请求速率。为此，我们使用 limits.method 选项。

<?php

use Chrisbjr\ApiGuard\Http\Controllers\ApiGuardController;

class BooksController extends ApiGuardController
{

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

}

上面的示例将限制对 show 方法的请求速率为每天 1000 请求。