README

介绍

此库提供了构建面向业务的OAuth API客户端的基本模块，非常容易使用。

功能

• 自动令牌协商
• API请求和响应的序列化和反序列化
• API响应的缓存层
• 易于扩展和定制

基本用法

简单请求

/** @var \Sidus\ApiClientBundle\ApiClient $apiClient */

$apiRequest = new \Sidus\ApiClientBundle\Model\Request\AuthenticatedApiRequest(
    new \Sidus\ApiClientBundle\Model\Request\Component\HttpComponent(
        baseUri: 'https://api.example.com',
        path: '/api/v1/resource',
    ),
);

$response = $apiClient->query($apiRequest);

$response->getBody(); // Raw response content

使用归一化/去归一化

/** @var \Sidus\ApiClientBundle\ApiClient $apiClient */

$apiRequest = new \Sidus\ApiClientBundle\Model\Request\AuthenticatedApiRequest(
    new \Sidus\ApiClientBundle\Model\Request\Component\HttpComponent(
        baseUri: 'https://api.example.com',
        path: '/api/v1/resource',
        method: 'POST',
    ),
);

$apiRequest->setSerializationComponent(
    new \Sidus\ApiClientBundle\Model\Request\Component\SerializationComponent(
        content: new Resource(),
    ),
);
$apiRequest->setDeserializationComponent(
    new \Sidus\ApiClientBundle\Model\Request\Component\DeserializationComponent(
        className: ResourceResponse::class,
    ),
);

$response = $apiClient->query($apiRequest);

$responseResource = $response->getContent(); // Deserialized response content

使用缓存

/**
 * @var \Sidus\ApiClientBundle\ApiClient $apiClient
 * @var \Sidus\ApiClientBundle\Model\Request\ApiRequest $apiRequest
 */
 
$apiRequest->setCacheComponent(
    new \Sidus\ApiClientBundle\Model\Request\Component\CacheComponent(
        ttl: 3600,
    ),
);

安装

composer require sidus/api-client-bundle

配置

您有两种方式提供令牌协商的凭据

声明一个凭据服务

services:
    app.oauth_credentials:
        class: Sidus\ApiClientBundle\Credentials
        arguments:
            $baseUrl: 'https://api.example.com'
            $path: '/oauth/token' # Token negotiation endpoint
            $authenticationParams: # What you send to the token negotiation endpoint
                username: 'xxxx'
                password: 'xxxx'

每次您使用相同的基地址创建API请求时，凭据将自动使用。

或者，您可以直接在API请求中提供访问令牌

$apiRequest = new \Sidus\ApiClientBundle\Model\Request\AuthenticatedApiRequest(
    new \Sidus\ApiClientBundle\Model\Request\Component\HttpComponent(
        baseUri: 'https://api.example.com',
        path: '/api/v1/resource',
    ),
);
$apiRequest->setAuthorizationComponent(
    new Sidus\ApiClientBundle\Model\Authorization\OAuthToken(
        accessToken: 'xxxx',
    ),
);

或者任何实现 \Sidus\ApiClientBundle\Contracts\Request\Component\AuthorizationComponentInterface 接口的自定义授权组件。

当使用自定义头时，只需在API请求中添加自定义头即可

$apiRequest->addHeader('X-Custom-Header', 'value');

或者使用事件监听器，通过使用 \Sidus\ApiClientBundle\Model\Event\ApiRequestEvent 事件自动添加头。