Api Exploration

HalExplorer is able to traverse links that exist on a PSR-7 Response. HalExplorer expects the response body to be correctly formatted according to the HAL draft. Malformed response bodies will not be traversed correctly.

To use the exploration feature of the library we need to think about our responses and their included _links, and _embedded as objects and their relationships.

Fetching, Creating, Updating, and Deleting are the primary actions to perform on a related object. HalExplorer exposes this functionality with the getRelation, createRelation, updateRelation, patchUpdateRelation and deleteRelation methods.

As expected, these methods map to GET, POST, PUT, PATCH and DELETE HTTP verbs.

For example, given the following response:

{
    "id": 123,
    "data": "information",
    "_links": {
        "curies": [
            {
                "name": "doc",
                "href": "/docs/{rel}",
                "templated": true
            }
        ],
        "relation": {
            "title": "A relationship link",
            "href": "/relationship/456"
        },
        "doc:association": {
            "title": "another relationship",
            "href": "/association/789"
        },
        "self": {
            "title": "A Self Referencing Link",
            "href": "/self/123"
        },
        "templated": {
            "title": "A templated Link",
            "href": "/place/{name}"
        },
        "old-link": {
            "title": "A old and deprecated Link",
            "href": "/oldplace",
            "deprecation": "http://more-information.com/oldplace"
        }
    },
    "_embedded": {
        "relation": {
            "this": "is an embedded relationship",
            "id": 456,
            "_links": {
                "self": {
                    "href": "/relationship/456"
                }
            }
        }
    }
}

Calling $association = $explorer->getRelation($object, "association"); will create a GET request to {baseUrl}/association/789 and return a the PSR-7 response object than can be further traversed by HalExplorer.

Similarially calling $relation = $explorer->createRelation($object, "relation") will create a POST request to the {baseUrl}/relationship/456 resource.

Request Options

You can pass any request specific HTTP Client options along using the third paramater of all exploration methods.

$post = $explorer->createRelation($object, "relation", [
    "form_params" => [
        "field1": "value1",
        "field2": "value2",
    ],
]);

Will create the POST request to {baseUrl}/relationship/456 and send along the post values of field1, and field2.

The passed options merge with the default options and will overwrite any matching keys.

Api Entrypoint.

On initialization of the HalExplorer you should set the baseUrl for the api. $explorer->setBaseUrl("http://mysite.com/api"); This url will be handled as the entrypoint to the target api. You can retreive the entrypoint response by calling the $explorer->enter() method. From the entrypoint you should be able to access all the resources exposed by the api.

Manual Requests

To create a manual request you can use the makeRequest method.

$response = $explorer->makeRequest("get", "resource/endpoint", $options);