Fetching Relationships

Introduction

A server must support fetching relationship data for every relationship URL provided as a self link as part of a relationship's links object. The relationship data returned is the resource identifiers for the related resources.

The examples in this chapter assume an API URL namespace of /api and the following routing:

JsonApi::register('default', ['namespace' => 'Api'], function ($api, $router) {
    $api->resource('posts', [
        'has-one' => 'author',
        'has-many' => 'tags'
    ]);
});

All querying of resources is handled via the Resource Adapter class for the resource type that is subject of the request. Relationship queries are handed off to a relationship adapter that is returned from the resource adapter's related method.

Relationship Data

A resource object may include a self link in a relationship. For example:

{
    "type": "posts",
    "id": "1",
    "relationships": {
        "author": {
            "links": {
                "self": "/api/posts/1/relationships/author"
            }
        }        
    }
}

For these queries, the adapter's related method is used to obtain a relationship adapter for the named relationship. The related resource(s) are then obtained from the relationship adapter using the relationship method.

To-One

A request for a to-one relationship's data is made as follows:

GET /api/posts/1/relationships/author HTTP/1.1
Accept: application/vnd.api+json

If the relationship is not empty, the resource identifier of the related resource will be returned in the data member of the JSON API document:

HTTP/1.1 200 OK
Content-Type application/vnd.api+json

{
    "data": {
        "type": "users",
        "id": "123"
    }
}

If the relationship is empty, the data member will be null:

HTTP/1.1 200 OK
Content-Type application/vnd.api+json

{
    "data": null
}

To-Many

A request for a to-many relationship's data is made as follows:

GET /api/posts/1/relationships/tags HTTP/1.1
Accept: application/vnd.api+json

The resource identifiers of the related resources will be returned in the data member of the JSON API document:

HTTP/1.1 200 OK
Content-Type application/vnd.api+json

{
    "data": [
        {
            "type": "tags",
            "id": "123"
        },
        {
            "type": "tags",
            "id": 456"
        }
    ]
}

If the relationship is empty, an empty array will be returned:

HTTP/1.1 200 OK
Content-Type application/vnd.api+json

{
    "data": []
}

Not Found

A request for relationship data will return a 404 Not Found response if the primary resource does not exist. So for the example above, if no posts resource with an id of 1 exists, the following would be returned:

HTTP/1.1 404 Not Found
Content-Type application/vnd.api+json

{
    "errors": [
        {
            "title": "Not Found",
            "status": "404"
        }
    ]
}