Experience Preview API

Experience fragment

An experience fragment is a reusable, composable piece of an experience that can be embedded into other experiences. Experience fragments are authored and previewed in Contentful and served exclusively via the preview host, so this endpoint is only available on the Experience Preview API.

Requests to the experience fragment endpoint require a preview access token.

Getting localized experience fragments

Requesting an experience fragment with a locale query parameter hydrates it with content in that locale, the same way as an experience:

GET https://preview.xdn.contentful.com/spaces/{spaceId}/environments/{envId}/fragments/{fragId}?locale=en-US
Whether a nonexistent locale returns a 404 depends on whether the experience fragment has locale-based publishing status recorded. Most experience fragments don’t, since locale-based publishing is tracked at the experience level — in that case any locale is accepted, and unresolved content falls back to null values (see below). If an experience fragment does have locale-based publishing status, requesting a locale that isn’t in it returns a 404, the same way it does for experiences — except the check only confirms the locale exists, not that it’s published, since experience fragments are only ever served in preview.

When an experience fragment has no locale-based publishing status, requesting a locale that doesn’t exist for the environment returns the experience fragment hydrated with null values for every contentProperty, along with a corresponding entry in the errors array for each one. Each node’s componentType still resolves to the component backing it, and designProperties still resolve normally, since design values aren’t locale-dependent — only content pulled from bound entries and assets fails to resolve:

1{
2  "sys": {
3    "id": "3foFgkr9iq8bWSZQtb2H1G",
4    "type": "Fragment"
5  },
6  "nodes": [
7    {
8      "componentType": {
9        "sys": {
10          "type": "ResourceLink",
11          "linkType": "Contentful:ComponentType",
12          "urn": "crn:contentful:::experience:spaces/$self/environments/$self/componentTypes/heading"
13        }
14      },
15      "contentProperties": {
16        "title": null
17      },
18      "designProperties": {
19        "shorten": {
20          "type": "ManualDesignValue",
21          "value": true
22        }
23      },
24      "slots": {}
25    },
26    {
27      "componentType": {
28        "sys": {
29          "type": "ResourceLink",
30          "linkType": "Contentful:ComponentType",
31          "urn": "crn:contentful:::experience:spaces/$self/environments/$self/componentTypes/mediaBanner"
32        }
33      },
34      "contentProperties": {
35        "imageSrc": null,
36        "imageAlt": null,
37        "caption": null
38      },
39      "designProperties": {
40        "aspectRatio": {
41          "type": "ManualDesignValue",
42          "value": "16:9"
43        },
44        "overlayOpacity": {
45          "type": "ManualDesignValue",
46          "value": "0.3"
47        }
48      },
49      "slots": {}
50    }
51  ],
52  "errors": [
53    {
54      "fieldPath": "Fragment.3foFgkr9iq8bWSZQtb2H1G.dataAssembly.cp_bmvVlHXzUz.title",
55      "message": "$on.type branch does not match runtime type 'undefined'.",
56      "originalError": {
57        "message": "$on.type branch does not match runtime type 'undefined'.",
58        "code": "MISSING_ON_TYPE_BRANCH",
59        "type": "MissingOnTypeBranchError",
60        "statusCode": 400
61      }
62    },
63    {
64      "fieldPath": "Fragment.3foFgkr9iq8bWSZQtb2H1G.dataAssembly.cp_nXb7fb5jWo.imageSrc",
65      "message": "$on.type branch does not match runtime type 'undefined'.",
66      "originalError": {
67        "message": "$on.type branch does not match runtime type 'undefined'.",
68        "code": "MISSING_ON_TYPE_BRANCH",
69        "type": "MissingOnTypeBranchError",
70        "statusCode": 400
71      }
72    }
73    // ...one error per contentProperty
74  ]
75}

Requesting an experience with a non-existent locale on preview always returns a 404, since every experience stores localeStatus and the API can always verify whether the requested locale exists. See Getting localized experiences.