xp-framework / rest
REST Client and Server APIs for the XP Framework
Installs: 61 879
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 1
Forks: 2
Open Issues: 2
Requires
- php: >=5.6.0
- xp-forge/json: ^3.0 | ^2.1
- xp-framework/collections: ^8.0 | ^7.0 | ^6.5
- xp-framework/core: ^9.1 | ^8.0 | ^7.0 | ^6.5
- xp-framework/http: ^9.0 | ^8.0 | ^7.0 | ^6.2
- xp-framework/logging: ^9.0 | ^8.0 | ^7.0 | ^6.5
- xp-framework/networking: ^9.0 | ^8.0 | ^7.0 | ^6.6
- xp-framework/scriptlet: ^9.0 | ^8.0.1
- xp-framework/tokenize: ^8.0 | ^7.0 | ^6.5
- xp-framework/xml: ^9.0 | ^8.0 | ^7.0 | ^6.0
Requires (Dev)
- xp-framework/io-collections: ^8.0 | ^7.0 | ^6.5
- xp-framework/unittest: ^9.0 | ^8.0 | ^7.0 | ^6.5
This package is auto-updated.
Last update: 2020-08-29 04:18:28 UTC
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/');