README

使用 Laravel 通过 API 密钥简单认证您的 API。此软件包使用了以下库

philsturgeon 的 Fractal
maximebeaudoin 的 api-response

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

已修复以与 LARAVEL 5.3.* 兼容

Laravel 5 终于支持了！

**Laravel 5.1.x 到 5.3.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 petyots/api-guard

在您的 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` 字段，您可以为此填充用户的用户 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次。