Uhura

A communications officer for RESTful APIs, _(*1)

Uhura is a dead simple RESTful API client for just about anything. No need to set up schemas or configure API endpoints, just tell Uhura what you want and go get it., _(*2)

$github = new Uhura('https://api.github.com');
$response = $github->users->colindecarlo->repos->get();

Installation

Install Uhura using composer., _(*3)

$ composer require uhura/uhura

Making Requests

Uhura maps what you ask for in your Demeter chain over to the URL that is used to access the resource you want., _(*4)

Examples

Send a GET request to http://someapi.com/users, _(*5)

$uhura = new Uhura('http://someapi.com');
$response = $uhura->users->get();

Send a GET request to http://someapi.com/users/1, _(*6)

$uhura = new Uhura('http://someapi.com');
$response = $uhura->users(1)->get();

Send a GET request to http://someapi.com/users/1/blogs/some-blog/comments, _(*7)

$uhura = new Uhura('http://someapi.com');
$response = $uhura->users(1)->blogs('some-blog')->comments->get();

CRUD

CRUD operations are super simple with Uhura and are mapped to the create, get, update and delete methods respectively., _(*8)

Operation	Method Signature
Create	`create($payload)`
Read	`get()`
Update	`update($payload)`
Delete	`delete()`

create(array $payload), _(*9)

Use Uhura's create method to create resources. The create method accepts an associative array of attributes which are sent to the API in the request body as a x-www-form-urlencoded string., _(*10)

$uhura = new Uhura('http://someapi.com');
$uhura->users->create(['email' => 'example@example.com']);

get(), _(*11)

Use Uhura's get method to get API resources., _(*12)

$uhura = new Uhura('http://someapi.com');
$response = $uhura->users->get();

update($payload), _(*13)

Use Uhura's update method to update a resource. The update method accepts an associative array of attributes which are sent to the API in the request body as a x-www-form-urlencoded string., _(*14)

$uhura = new Uhura('http://someapi.com');
$uhura->users(1)->update(['name' => 'John Doe']);

delete(), _(*15)

Use Uhura's delete method to delete a resource., _(*16)

$uhura = new Uhura('http://someapi.com');
$uhura->users(1)->delete();

Authentication

Uhura makes authenticated requests by adding the Authorization header to each request that is made., _(*17)

Using HTTP Basic Auth, _(*18)

Tell Uhura to use HTTP Basic Auth with the useBasicAuthentication($username, $password) method., _(*19)

$uhura = new Uhura('https://someapi.com');
$uhura->useBasicAuthentication('someuser', 'somepassword');

$uhura->user->update(['email' => 'example@example.com']);

Explicitly Setting the Authorization Header, _(*20)

You can explicitly set the value of the Authorization header by using Uhura's authenticate($token) method., _(*21)

$uhura = new Uhura('https://someapi.com');
$uhura->authenticate('Bearer somebearertoken');

$uhura->user->update(['email' => 'example@example.com']);

Working With Responses

By default, Uhura returns PSR7 compliant response objects. Working with them would be as simple as, oh I don't know, a GuzzleHttp\Psr7\Response object., _(*22)

Response Handlers

You can tell Uhura to pass API responses through a Response Handler to augment the return value of the various request methods. For instance, Uhura ships with a Json Response Handler which consumes the response and returns the decoded JSON response body., _(*23)

$uhura = new Uhura('https://someapi.com');
$uhura->useResponseHandler(new Uhura\ResponseHandler\Json);

$uhura->users(1)->get();
/*
    [
        'email' => 'example@example.com',
        'name' => 'John Doe'
    ]
*/

Writing Custom Response Handlers, _(*24)

Writing your own custom response handler is super simple. Response Handlers are just simple classes which define a handle($response) method. Whatever is returned from the handle method is what Uhura will return to you., _(*25)

// XML Response Handler
class XmlHandler
{
    public function handle($response)
    {
        return new SimpleXMLElement($response->getBody()->getContents());
    }
}


$uhura = new Uhura('https://someapi.com');
$uhura->useResponseHandler(new XmlHandler);

echo (string)($uhura->users(1)->get());

/*
    
    <user>
        <email>example@example.com</email>
        <name>John Doe</name>
    </user>
*/