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 in the GraphQL Content API as a sys object containing urn and linkType:

As they are part of another space, resolving cross-space linked entities requires a special header to be passed in each request namedx-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": "<cda-token>",
4
    "anotherSpaceId": "<cda-token>"
5
  }
6
}

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

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.

Example query

1
query pageEntryQuery {
2
  landingPage(id: "7wGhPNCZNLknpSaJVWfnHf") {
3
    # ResourceLink field
4
    headline {
5
      sys {
6
        urn
7
      }
8
      node {
9
        ... on Headline_SpaceB_Alias-1 {
10
          title
11
          # ResourceLink field, but does not resolve because only 1 level is supported.
12
          subheadline {
13
            sys {
14
              urn
15
            }
16
          }
17
        }
18
      }
19
    }
20
  }
21
}

Capabilities

• The locale and useFallbackLocale query parameters are propagated to all extra spaces present in the x-contentful-resource-resolution header.
• Publishing new content in any of the extra spaces will cause the cache to be purged on every request that included that space ID.
• Cross-space queries support preview requests if the preview token is provided.

Usage

Cross-space references can be resolved through the use of a special node field for content types which have a linked reference from another space. Fields of the referenced content type are accessed with an inline fragment with a type name in the following format: {CONTENT_TYPE}_{SPACE}_{ENVIRONMENT}.

1
query {
2
  authorCollection {
3
    items {
4
      writings {
5
        node {
6
          ... on novel_4n0th3rSp4c3_Master {
7
            title
8
          }
9
        }
10
        # ResourceLink properties
11
        sys {
12
          linkType
13
          urn
14
        }
15
      }
16
    }
17
  }
18
}

Limitations

• Up to 4 spaces can be resolved in a single request.
• Only 3 extra space tokens are supported. You can make a single API call that resolves up to 4 spaces at the same time: 3 extra spaces and the entries from the space ID in the initial request.
• Only the first level of cross-space references is resolved from the original space ID 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 x-contentful-resource-resolution header will also consume Rate Limiting from the space IDs present in it when the request is uncached.
• No Advanced Caching support.

For more information, see the Resource Links FAQs.