REST Client and Server APIs for the XP Framework

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/');

xp-framework/rest