README

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