JSON API Client

Build Status SensioLabsInsight

Abstract client-side PHP implementation of the json api specification, based on the PSR-7 HTTP message interface.

Installation

composer require enm/json-api-client

You can use the default HTTP implementation (Enm\JsonApi\HttpClient\GuzzleAdapter) which requires a Guzzle client.

composer require guzzlehttp/guzzle ^6.0

If needed you can also implement the interface by yourself to use any HTTP client which supports PSR-7.

Usage

First you should read the docs at enm/json-api-common where all basic structures are defined.

Your API client for sending requests to a JSON API and get validated responses as JSON API documents is an instance of Enm\JsonApi\Client\JsonApiClient, which requires a HTTP client (Enm\JsonApi\HttpClient\HttpClientInterface) to execute requests.

Method Return Type Description
createJsonApiRequest(string $type, string $id = ‘’) JsonApiRequestInterface Create a new JSON API request object, needed for a delete request.
createFetchRequest(string $type, string $id = ‘’) FetchRequestInterface Create a new fetch request object, needed for fetch requests.
createSaveSingleResourceRequest(ResourceInterface $resource, bool $patch = false) SaveRequestInterface Create a new save request object, needed for create or patch requests.
fetch(FetchRequestInterface $request) DocumentInterface Execute a fetch request for one or many resources and transform the server response into a JSON API document.
save(SaveRequestInterface $request) DocumentInterface Execute a save (create or patch) request and transform the server response into a JSON API document.
delete(JsonApiRequestInterface $request) DocumentInterface Execute a delete request and transform the server response into a JSON API document.
fetchRelationship(string $relationship, FetchRequestInterface $request, bool $onlyIdentifiers = false) DocumentInterface Execute a fetch request for a relationship and transform the server response into a JSON API document.
follow(LinkInterface $link, array $headers = []) DocumentInterface Execute a fetch request which is defined by a JSON API link object and transform the server response into a JSON API document.
// configure http client and api endpoint
$guzzle = new Client(); // if you are using guzzle htttp
$baseUri = 'http://example.com/api' // the base uri for all api requests

// create the api client
$apiClient = new JsonApiClient($baseUri, new GuzzleAdapter($guzzle));

// create a fetch request to retrieve a single resource
$request = $apiClient->createFetchRequest('myResourceType', 'myResource');
$request->include('myRelationship'); // include a relationship

// get a response from server
$document = $apiClient->fetch($request);

$myResource = $document->data()->first(); // the resource fetched by this request
$myIncludedResources = $document->included()->all(); // the included resources fetched with the include parameter

##############

// create a fetch request to retrieve all resource of a type
$requestAll =  $apiClient->createFetchRequest('myResourceType');

// get a response from server
$collectionDocument = $apiClient->fetch($request);
$resources = $collectionDocument->data()->all(); // all resources from the current response

##############

// create a new resource
$resource = $apiClient->resource('examples', 'example-1');

$request = $apiClient->createSaveSingleResourceRequest($resource);
$response = $apiClient->save($request);

// update the created resource
$resource = $response->data()->first(); // get the created resource from response
$resource->attributes()->set('title', 'Example');

$request = $apiClient->createSaveSingleResourceRequest($resource);
$response = $apiClient->save($request);