Hypermedia API Client
An experimental hypermedia API client designed to fulfil the HATEOAS part of REST.
Only HTTP(s) is supported in a useful state right now, as it's by far the most used mechanism for APIs currently, though since HTTP is not a requirement for RESTful APIs, the interface presented by this library will aim to be protocol agnostic.
By understanding common content-types and standards where available (and allowing flexible configuration otherwise) we are able to provide an expressive syntax to navigating and interacting with APIs.
- Iteration over collections, even when paginated
- Support for following hypermedia links
- Support for performing actions through hypermedia controls
Support for various formats and standards
- JSON HyperSchema
- HAL Forms
- OpenAPI / Swagger
How it works
To begin interacting with an API, you need an
ApiClient. Initialise one with an array of supported protocols. An
example, using HTTP and Guzzle looks like this:
use AdamQuaile\HypermediaApiClient\ApiClient; use AdamQuaile\HypermediaApiClient\EventDispatcher; use AdamQuaile\HypermediaApiClient\Protocols\Http\HttpProtocol; $apiClient = new ApiClient( [ new HttpProtocol( \Http\Adapter\Guzzle6\Client::createWithConfig([ 'timeout' => 5 ]), new \Http\Message\MessageFactory\GuzzleMessageFactory() ) ], new EventDispatcher() );
The built-in HTTP protocol class uses HttPlug for it's HTTP abstraction, can support many libraries such as cURL and Guzzle. You can also provide test adapters for testing your apps or integrations.
Now that's set up, you can load a resource:
$images = $apiClient->loadFromUri('https://api.digitalocean.com/v2/images');
From here you can interact with the resource, get data from the response, iterate over lists and follow and act upon hypermedia links defined in the API.
Taking advantage of REST
You'll need to teach your client how to understand how the APIs you're interacting with work. Perhaps it's using JSON:API, maybe it's using HAL or JSON HyperSchema. This is where extensions come in.
As the hypermedia client loads a resource and delegates that loading to the protocol, they emit various events through the event dispatcher. Extensions listen to these events and provide the ability to parse various content types and understand various hypermedia description formats.
Using REST-ish APIs
While hypermedia controls are a requirement for REST, and help to decouple an API and its integrations, not all APIs are RESTful. Whether they claim to be or not, some simply aren't. This does not make them inherently bad APIs, but you will need to do a bit of extra work in order to use them with this hypermedia based client.