level3/resource

Level3 Resource is a library for representing resources and consuming in different hypermedia formats.

Level3 Resource

Level3 Resource is a library for representing and consuming resources in different hypermedia formats., _(*1)

A resource in a [HATEOAS API] (http://en.wikipedia.org/wiki/HATEOAS) must describe its own capabilities and interconnections, which is the third level of Three Levels of the REST Maturity Model, _(*2)

Why Hypermedia?

As you can read in the prologue of Designing Hypermedia APIs book:, _(*3)

Hypermedia APIs embrace the principles that make the web great: flexibility, standardization, and loose coupling to any given service. They take into account the principles of systems design enumerated by Roy Fielding in his thesis, but with a little less sytems theory jargon., _(*4)

Hypermedia designs scale better, are more easily changed and promote decoupling and encapsulation, with all the benefits those things bring. On the downside, it is not necessarily the most latency-tolerant design, and caches can get stale if you're not careful. It may not be as efficient on an individual request level as other designs., _(*5)

-- Steve Klabnik, _(*6)

Which Hypermedia specification should I use?

Hypermedia is being defined these days. Only the best APIs implement Hypermedia. Currently there is no de facto standard, so you must choose between the differents specifications., _(*7)

Level3 Resource currenly implements or is planned to implement these specifications: * HAL: This is the most common and active. It has a JSON and a XML version. * Siren: Currently being defined. It implements some useful things like actions, classes, etc. * Collection+JSON: This is fully designed to be a CRUD oriented API., _(*8)

Requirements

• PHP 5.4.x
• hampel/json >= 1.0

Installation

The recommended way to install Level3 Resource is through composer. You can see the package information on Packagist., _(*9)

{
    "require": {
        "level3/resource": "dev-master"
    }
}

Examples

Writer

Basic Resource with Link as application/hal+json

use Level3\Resource\Link;
use Level3\Resource\Resource;
use Level3\Resource\Format\Writer\HAL;

$resource = new Resource();
$resource->setURI('/foo');
$resource->setLink('foo', new Link('/bar'));
$resource->setData([
    'foo' => 'bar',
    'baz' => 'qux'
]);

$writer = new HAL\JsonWriter(true);
echo $writer->execute($resource);

{
    "foo": "bar",
    "baz": "qux",
    "_links": {
        "self": {
            "href": "/foo"
        },
        "foo": {
            "href": "/bar"
        }
    }
}

Resource with embedded resources as aapplication/vnd.siren+json

use Level3\Resource\Link;
use Level3\Resource\Resource;
use Level3\Resource\Format\Writer\Siren;

$resource = new Resource();
$resource->setRepositoryKey('index');
$resource->setURI('/index?page=2');
$resource->setLink('prev', new Link('/index?page=1'));
$resource->setLink('next', new Link('/index?page=3'));
$resource->addData('count', 5);

$subresource = [];
foreach (range(1, 5) as $value) {
    $subresource = new Resource();
    $subresource->addData('value', $value);

    $subresources[] = $subresource;
}

$resource->addResources('subresources', $subresources);

$writer = new Siren\JsonWriter(true);
echo $writer->execute($resource);

{
    "class": [
        "index"
    ],
    "properties": {
        "count": 5
    },
    "entities": [
        {
            "rel": "subresources",
            "class": [
                "index",
                "subresources"
            ],
            "properties": {
                "value": 1
            }
        },
        ...
        {
            "rel": "subresources",
            "class": [
                "index",
                "subresources"
            ],
            "properties": {
                "value": 5
            }
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "/index?page=2"
        },
        {
            "rel": "prev",
            "href": "/index?page=1"
        },
        {
            "rel": "next",
            "href": "/index?page=3"
        }
    ]
}

Resource with linked resource as application/hal+xml

use Level3\Resource\Link;
use Level3\Resource\Resource;
use Level3\Resource\Format\Writer\HAL;

$author = new Resource();
$author->setURI('/john-doe');
$author->setTitle('John Doe');

$article = new Resource();
$article->setURI('/lorem-ipsum');
$article->addData('description', 'Lorem ipsum dolor sit amet ...');
$article->linkResource('author', $author);

$writer = new HAL\XMLWriter(true);
echo $writer->execute($article);

<?xml version="1.0"?>
<resource href="/lorem-ipsum">
  <description>Lorem ipsum dolor sit amet ...</description>
  <link rel="author" href="/john-doe" title="John Doe"/>
</resource>

Reader

Basic Resource with Link as application/hal+json

use Level3\Resource\Format\Reader\HAL;

$json = '{"foo":"bar","baz":"qux","_links":{"self":{"href":"/foo"},"foo":{"href":"/bar"}}}';

$reader = new HAL\JsonReader();
$resource = $reader->execute($json);
print_r($resource);

Level3\Resource\Resource Object
(
    [uri:protected] => /foo
    [links:protected] => Array
        (
            [foo] => Level3\Resource\Link Object
                (
                    [href:protected] => /bar
                )

        )

    [data:protected] => Array
        (
            [foo] => bar
            [baz] => qux
        )

)

Tests

Tests are in the tests folder. To run them, you need PHPUnit. Example:, _(*10)

$ phpunit --configuration phpunit.xml.dist

License

MIT, see LICENSE, _(*11)