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:

{
  "spaces": {
    "someSpaceId": "<cda-token>",
    "anotherSpaceId": "<cda-token>"
  }
}

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.

const extraTokens = {
  spaces: {
    IdToR3s0lv3: 'ND63YKcYBe335RWDnIuzv...',
    '4n0th3rSp4c3': 'UuVe6icuBuXv...',
  },
}
// Converts object to string and uses base64 to encode the string
window.btoa(JSON.stringify(extraTokens)) // eyJzcGFjZXMiOnsiSWRUb1I[...]=

The value can then be passed to the x-contentful-resource-resolution header as-is.

Example query

query pageEntryQuery {
  landingPage(id: "7wGhPNCZNLknpSaJVWfnHf") {
    # ResourceLink field
    headline {
      sys {
        urn
      }
      node {
        ... on Headline_SpaceB_Alias-1 {
          title
          # ResourceLink field, but does not resolve because only 1 level is supported.
          subheadline {
            sys {
              urn
            }
          }
        }
      }
    }
  }
}

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}.

query {
  authorCollection {
    items {
      writings {
        node {
          ... on novel_4n0th3rSp4c3_Master {
            title
          }
        }
        # ResourceLink properties
        sys {
          linkType
          urn
        }
      }
    }
  }
}

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.