Resource Links

Resource Links are part of the Cross-space references feature set that allows you to link content across multiple spaces. It mainly uses ResourceLink links as a way to represent a relationship between entities from different spaces.

ResourceLink links are represented as a sys object containing urn, linkType and type:

As they are part of another space, resolving cross-space linked entities requires a special header to be passed in each request named x-contentful-resource-resolution.

Extra header for cross-space resolution

The x-contentful-resource-resolution header is a base64 encoded JSON object containing key-value pairs of spaceId/API Key. The plain JSON used to create the header should have the following shape:

1
{
2
    "spaces": {
3
        "someSpaceId": "<access-token>",
4
        "anotherSpaceId": "<access-token>"
5
    }
6
}

That then needs to be stringified and encoded to base64. You can use JSON.stringify and btoa (JavaScript) to properly convert the JSON object to a stringified encoded version of it.

Here is a full example in JavaScript:

1
const extraTokens = {
2
  "spaces": {
3
    "IdToR3s0lv3": "ND63YKcYBe335RWDnIuzv...",
4
    "4n0th3rSp4c3": "UuVe6icuBuXv..."
5
  }
6
}
7
8
// Converts object to string and uses base64 to encode the string
9
window.btoa(JSON.stringify(extraTokens)) // eyJzcGFjZXMiOnsiSWRUb1I[...]=

The value can then be passed to the x-contentful-resource-resolution header as-is. All cross-space references of matching space IDs will be returned within the includes property of the response.

Capabilities

• The locale query parameter is propagated to all extra spaces present in the new header.
• Only the first level of references of every extra space in the new header will be resolved. It applies to only one level of space. This is a behavior similar to include=1.
• The main space (space Id being requested in the URL) will still resolve up to 10 levels.
• Publishing new content in any of the extra spaces will cause the cache to be purged on every request that included that space Id.
• The includes property of the response will include both cross-space entries and assets.
• You can pass this new header in the Javascript SDK for automatic resolution.

Errors

Errors from cross-space requests are propagated back to the response payload in the errors property. If a request to a single cross-space fails, the main space request and other spaces will still continue to process.

Errors property example

1
{
2
    "errors": [
3
        {
4
            "details": {
5
                "urn": "crn:contentful:::content:spaces/<spaceId>/environments/<environmentId>/entries/<entryId>",
6
                "linkType": "Contentful:Entry",
7
                "type": "ResourceLink"
8
            },
9
            "sys": {
10
                "id": "notResolvable",
11
                "type": "error"
12
            }
13
        }
14
15
    ]
16
}

Limitations

• Up to 21 spaces to be resolved in a single request
• Only 20 extra space tokens are supported. You can make a single API call that resolves up to 21 spaces at the same time: 20 extra spaces and the entries from the space Id in the initial request.
• Up to 1000 references in the includes property in the response.
• Only the first level of cross-space references is resolved from the original spaceId in the URL
• The Authorization header is still required for every request and it should enable access to the main space Id in the URL.
• Errors from the extra space tokens will be returned in the errors property of the response.
• Using the new header will also consume the Rate Limiting from the space Ids present in it when the request is uncached.
• No Advanced Caching support
• No MRDI support

For more information, see the Resource Links FAQs.

Retrieval of linked Resource Links

Notes:

• The include parameter resolves links between entries and assets within a space. Links between content types within a space are not included in the response.
• The include parameter is only available for the entry collection endpoint /spaces/{space_id}/environments/{environment_id}/entries.

To retrieve linked Resource Links, use the Get all entries of a Space endpoint.