linkorb/primate

Primate: Restful API Library

Primate: The API ToolKit

, _(*1)

Primate is a library that helps creating beautiful REST APIs., _(*2)

It is heavily inspired by Stormpath's "The Fundamentals of REST API Design", _(*3)

Using Primate

First you'll need to instantiate Primate, before your app can serve requests:, _(*4)

use Primate\Primate;

$primate = new Primate();
$primate->setBaseUrl('http://primate.example.com/api/v1');
$primate->setProperty('tenant', 'joe');
$primate->setProperty('x', 'y');

You'll notice that the BaseUrl of your API is set on the Primate instance, in order to output correct urls., _(*5)

Additionally, we're registering some arbitrary properties to define the context of the requests. You can use these properties later in order to fetch resources., _(*6)

Resources and Collections

In Primate APIs, a client can work with Resources and Collections., _(*7)

• A Resource is simply an "object" in your application. For example, a User, a Product, etc.
• A Collection is simply an array of Resources.

Types

Each Resource is of a specified Type., _(*8)

In Primate, you'll need to register one or more Types before you can use them. For example:, _(*9)

$repo = new MyContactRepository();
$type = new Type('contacts', $repo);
$primate->registerType($type);

Each Type has a name and a repository. The Repository can be any class that's implementing the Primate\RepositoryInterface., _(*10)

It's recommended to take your existing application repositories, and make them implement this interface., _(*11)

For example:, _(*12)

<?php

namespace Example;

use Primate\RepositoryInterface;
use Primate\Resource;
use Primate\Primate;
use RuntimeException;

class PdoContactRepository implements RepositoryInterface
{
    public function __construct($pdo)
    {
        $this->pdo = $pdo;
    }

    // Implement your regular repository methods here...

    public function loadResourceCollection(Collection $collection, Primate $primate)
    {
        foreach ($this->getAllContacts() as $contact) {
            $resource = new Resource($collection->getType(), $contact->getId());
            $collection->addResource($resource);
        }
    }

    public function loadResources($resources, Primate $primate)
    {
        foreach ($resources as $resource) {
            $contact = $this->findById($resource->getId());
            $resource->setProperty('name', $contact->getName());
            $resource->setProperty('gender', $contact->getGender());
            $phoneResource = $primate->createResource('phones', $contact->getPhoneId());
            $resource->setProperty('phone', $phoneResource);
        }
    }
}

Primate will call these methods to load resource data., _(*13)

Calling Primate

You can make requests to Primate like this:, _(*14)

$data = $primate->getDataByPath($path, $expands);
echo json_encode($data, JSON_PRETTY_PRINT|JSON_UNESCAPED_SLASHES);

The path variable is either:, _(*15)

• /{typeName}: This will return a collection of all resources of that type
• /{typeName}/{resourceId}: This will return the specific resource

Additionally, you can pass an array of expands., _(*16)

Sub-resource expansion

When passing keys in the expands parameter, Primate will automatically expand the specified sub-resources., _(*17)

For example, if your first response looks like this:, _(*18)

{
    "href": "http://primate.example.com/api/v1/contacts/1",
    "name": "Alice",
    "gender": "Female",
    "phone": {
        "href": "http://primate.example.com/api/v1/phones/xyz"
    }
}

You can ask Primate to 'expand the phone property:, _(*19)

{
    "href": "http://primate.example.com/api/v1/contacts/1",
    "name": "Alice",
    "gender": "Female",
    "phone": {
        "href": "http://primate.example.com/api/v1/phones/xyz",
        "number": "+1 987654321",
        "type": "mobile"
    }
}

License

MIT (see LICENSE.md), _(*20)

Brought to you by the LinkORB Engineering team

Check out our other projects at linkorb.com/engineering., _(*21)

Btw, we're hiring!, _(*22)