sidus/api-client-bundle

Ease the creation of business API client with authentication, serialization and cache

v1.0.3 2024-09-04 15:44 UTC

Requires

• php: >=8.1
• psr/http-client: >1.0
• psr/http-factory: >1.0
• symfony/cache-contracts: >2.0
• symfony/serializer: >5.3

Requires (Dev)

• nyholm/psr7: *
• symfony/http-client: *

MIT

• Vincent Chalnot

• api
• cache
• client
• oauth
• serializer
• sidus

README

Introduction

This library provides basic blocks for building a business oriented OAuth API client very easily.

Features

• Automatic token negotiation
• Serialization and deserialization of API requests and responses
• Cache layer for API responses
• Easy to extend and customize

Basic usage

Simple request:

/** @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

Using normalizations/denormalization:

/** @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

Using cache:

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

Installation

composer require sidus/api-client-bundle

Configuration

You have two options to provide credentials for token negotiation:

Declare a Credentials service:

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'

Each time you create an API request using the same base URL, the credentials will be automatically used.

Or you can provide the access token directly in the API request:

$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',
    ),
);

Or any custom authorization component implementing the \Sidus\ApiClientBundle\Contracts\Request\Component\AuthorizationComponentInterface.

When using custom headers, simply add the custom header in the API request:

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

Or use an event listener to add the header automatically using the \Sidus\ApiClientBundle\Model\Event\ApiRequestEvent event.