zooxsmart/los-api-client

REST API Client using Hal

3.0.0 2024-10-10 14:23 UTC

Requires

• php: ^8.1
• ext-json: *
• ext-mbstring: *
• guzzlehttp/guzzle: ^7.8
• guzzlehttp/psr7: ^2.6
• laminas/laminas-eventmanager: ^3.12
• laminas/laminas-paginator: ^2.18
• psr/container: ^1.0 || ^2.0
• psr/link: ^1.0
• psr/simple-cache: ^1.0
• ramsey/uuid: ^4.7

Requires (Dev)

• doctrine/coding-standard: ^12.0.0
• phpstan/phpstan: ^1.10
• squizlabs/php_codesniffer: ^3.7.2

Suggests

• zooxsmart/los-log: zooxsmart/los-log for logging

MIT

• Leandro Silva

• rest
• api
• client
• hal

README

ApiClient is a php library to consume Restful APIs using Hal, like Apigility.

Requirements

Please, see composer.json

Installation

php composer.phar require los/api-client

Configuration

You need to configure at least the Api URI.

If using a framework that implements container-interopt, you can use the following configuration:

Copy the los-api-client.global.php.dist from this module to your application's config folder and make the necessary changes.

'los' => [
    'api-client' => [
        'root_uri' => 'http://localhost:8000',
        'add_request_id' => true,
        'add_request_time' => true,
        'add_request_depth' => true,
        'headers' => [
            'Accept'       => 'application/hal+json',
            'Content-Type' => 'application/json',
        ],
        'query' => [
            'key' => '123',
        ],
        'request_options' => [
            'request_options' => [
                'timeout' => 10,
                'connect_timeout' => 2,
                'read_timeout' => 10,
            ],
        ],
        'default_ttl' => 600,
    ],
],

Usage

Creating the client

You can use the Los\ApiClient\ClientFactory using the above configuration or manually:

$client = new \Los\ApiClient\ApiClient('http://api.example.com');

Single resource

/* @var \Los\ApiClient\ApiClient $client */
$client = new \Los\ApiClient\ApiClient('http://api.example.com');

/* @var \Los\ApiClient\Resource\ApiResource $ret */
$ret = $client->get('/album/1');

// $data is an array with all data and resources (_embedded) from the response
$data = $ret->getData();

Collection

/* @var \Los\ApiClient\ApiClient $client */
$client = new \Los\ApiClient\ApiClient('http://api.example.com');

/* @var \Los\ApiClient\Resource\ApiResource $ret */
$ret = $client->get('/album', [ 'query' => ['year' => 2018] ]);

// $data is an array with all data and resources (_embedded) from the response
$data = $ret->getData();

// $data is an array with the first album resource from the response
$data = $ret->getFirstResource('album');

// $data is an array with the all album resources from the response
$data = $ret->getResources('album');

// $data is an array with the all resources from the response
$data = $ret->getResources();

Cache

/* @var \Psr\SimpleCache\CacheInterface */
$cache = null; // Any PSR-16 cache service. 

/* @var \Los\ApiClient\ApiClient $client */
$client = new \Los\ApiClient\ApiClient('http://api.example.com', $cache);

// The last param is a per item ttl, please make sure your cache service can handle it.
/* @var \Los\ApiClient\Resource\ApiResource $ret */
$ret = $client->getCached('/album', 'cached-key', [ 'query' => ['year' => 2018] ], null);

// $data is an array with all data and resources (_embedded) from the response
$data = $ret->getData();

// $data is an array with the first album resource from the response
$data = $ret->getFirstResource('album');

// $data is an array with the all album resources from the response
$data = $ret->getResources('album');

// $data is an array with the all resources from the response
$data = $ret->getResources();

Events

The client triggers some events:

• request.pre
• request.post
• request.fail

More info about events on zend-eventmanager.

Request Id

The client automatically adds a X-Request-Id to each request, but only if there is no previous X-Request-Id added.

You can force a new id with:

$client = $this->getServiceLocator()->get('hermes');
$client->addRequestId(); // Auto generared
$client->addRequestId('123abc');