/rest

REST Client and Server APIs for the XP Framework

Primary LanguagePHP

REST Client and Server APIs for the XP Framework

Build Status on TravisCI XP Framework Module BSD Licence Required PHP 5.6+ Supports PHP 7.0+ Required HHVM 3.4+ Latest Stable Version

Client

Entry point

The Endpoint class serves as the entry point to this API. Create a new instance of it with the REST service's endpoint URL and then invoke its resource() method to work with the resources.

Creating: post

$api= new Endpoint('http://api.example.com/');
$response= $api->resource('users')->post(['name' => 'Test'], 'application/json');

// Check status codes
if (201 !== $response->status()) {
  throw new IllegalStateException('Could not create user!');
}

// Retrieve response headers
$url= $response->header('Location');

Reading: get / head

$api= new Endpoint('http://api.example.com/');

// Unmarshal to object by optionally passing a type; otherwise returned as map
$user= $api->resource('users/self')->get()->data(User::class);

// Test for existance with HEAD
$exists= (200 === $api->resource('users/1549')->head()->status());

// Pass parameters
$list= $api->resource('user')->get(['page' => 1, 'per_page' => 50])->data();

Updating: put / patch

$api= new Endpoint('http://api.example.com/');
$resource= $api->resource('users/self')
  ->using('application/json')
  ->accepting('application/json')
;

// Default content type and accept types set on resource used
$updated= $resource->put(['name' => 'Tested', 'login' => $mail])->data();

// Resources can be reused!
$updated= $resource->patch(['name' => 'Changed'])->data();

Deleting: delete

$api= new Endpoint('http://api.example.com/');

// Pass segments
$api->resource('user/{id}', ['id' => 6100])->delete();

Execute

If you need full control over the request, use the generic execute() method.

use webservices\rest\Endpoint;
use webservices\rest\RestRequest;
use peer\http\HttpConstants;

$api= new Endpoint('http://api.example.com/');

$request= (new RestRequest('/resource/{id}'))
 ->withMethod(HttpConstants::GET)
 ->withSegment('id', 5000)
 ->withParameter('details', 'true')
 ->withHeader('X-Binford', '6100 (more power)'
;

$response= $api->execute($request);
$content= $response->content();            // Raw data as string
$value= $response->data();                 // Deserialize to map

Deserialization

The REST API supports automatic result deserialization by passing a type to the data() method.

use com\example\api\types\Person;

$person= $response->data(Person::class);
$strings= $response->data('string[]');
$codes= $response->data('[:int]');

Authentication

Basic authentication is supported by embedding the credentials in the endpoint URL:

use webservices\rest\Endpoint;

$api= new Endpoint('http://user:pass@api.example.com/');