Resource Entities

Entities overview

With Native external references, we introduce the following new entity types that allow us to model data from third-party systems, such as MockShop, in Contentful:

• Resource Provider - A third-party system that provides resources. Each provider can have multiple resource types. In our tutorial example, this is a MockShop provider.

• Resource Type - A specific type of resource (not the resource itself) provided by a resource provider. In our tutorial example, this is Product.

Below is a representation of how a Resource Provider is structured, using the MockShop app as an illustrative example.

1
{
2
  "sys": { "id": "MockShop" },
3
  "type": "function",
4
  "function": {
5
    "sys": {
6
      "type": "Link",
7
      "linkType": "Function",
8
      "id": "externalResources"
9
    }
10
  }
11
}

We are representing Resource Types in a similar structure:

1
{
2
  "sys": { "id": "MockShop:Product" },
3
  "name": "Product",
4
  "defaultFieldMapping": {
5
    "title": "{ /title }",
6
    "subtitle": "Product ID: { /id }",
7
    "image": {
8
      "url": "{ /featuredImage/url }",
9
      "altText": "{ /featuredImage/altText }"
10
    }
11
  }
12
}

Code walkthrough

The example app is using Functions to provide a connection between Contentful and the MockShop API. In the functions/mockShop.ts file we are defining events that are necessary for Native external references to function properly:

• search - retrieval of specific content based on search queries
• lookup - retrieval of specific content based on URNs (IDs)
• graphql.resourcetype.mapping - retrieval of resource type mappings, which determines what fields in Contentful map to an external type in Graph API.
• graphql.query - handles GraphQL queries for the external third-party API.

Search request

Search handler expects the following shape for outgoing requests:

1
type ResourcesSearchRequest = {
2
  type: 'resources.search';
3
  resourceType: string;
4
  query?: string;
5
  locale?: string;
6
  referencingEntryId?: string;
7
  limit: number;
8
  pages?: {
9
    nextCursor: string;
10
  };
11
};

Lookup request

Lookup handler expects the following shape for outgoing requests:

1
type Scalar = string | number | boolean;
2
3
type ResourcesLookupRequest<
4
  L extends Record<string, Scalar[]> = Record<string, Scalar[]>
5
> = {
6
  type: 'resources.lookup';
7
  resourceType: string;
8
  lookupBy: L;
9
  locale?: string;
10
  referencingEntryId?: string;
11
  limit?: number;
12
  pages?: {
13
    nextCursor: string;
14
  };
15
};

This event is triggered to render preview cards in the Entry editor and when resolving Native External References in delivery. See CDA documentation.

Differentiate the context by checking context.originalRequest?.headers['contentful-api']: cda for Content Delivery API, cpa for Content Preview API, or undefined for CMA/WebApp requests.

Lookup and Search response

Both events return the same shape of the response:

1
type Product = {
2
  urn: string;
3
  title: string;
4
  featuredImage?: {
5
    url: string;
6
    altText?: string;
7
  };
8
  badge: {
9
    variant: string;
10
    label: string;
11
  };
12
};
13
14
type ResourcesSearchResponse = {
15
  items: Product[];
16
  pages: {
17
    nextCursor?: string;
18
  };
19
};
20
21
type ResourcesLookupResponse = {
22
  items: Product[];
23
  pages: {
24
    nextCursor?: string;
25
  };
26
};

Functions are designed without prior knowledge of the response data structure from third-party systems. Therefore, an additional transformation is required to ensure that all Function events return responses with a consistent shape of Products. This transformation is carried out by the withBadge and withUrn functions located in the function/utils.ts file. In our example, we are expecting Resource to conform to a particular shape:

1
type Product = {
2
  urn: string;
3
  title: string;
4
  featuredImage?: {
5
    url: string;
6
    altText?: string;
7
  };
8
  badge: {
9
    variant: string;
10
    label: string;
11
  };
12
};

GraphQL query request

GraphQL Query handler expects the following shape for outgoing requests:

1
type GraphQLQueryRequest = {
2
  type: 'graphql.query';
3
  query: string;
4
  isIntrospectionQuery: boolean;
5
  variables: Record<string, unknown>;
6
  operationName?: string;
7
};

GraphQL query response

The GraphQL query response adheres to the standard GraphQL specification.

1
/**
2
 * @see https://spec.graphql.org/October2021/#sec-Response
3
 */
4
type GraphQLQueryResponse = {
5
  data?: Record<string, any> | null;
6
  errors?: readonly Record<string, any>[];
7
  extensions?: Record<string, unknown>;
8
};

GraphQL resourcetype mapping request

GraphQL resourcetype mapping handler expects the following shape for outgoing requests:

1
type GraphQLResourceTypeMappingRequest = {
2
  type: 'graphql.resourcetype.mapping';
3
  resourceTypes: {
4
    resourceTypeId: string;
5
  }[];
6
};

GraphQL resourcetype mapping response

Here is the typing for GraphQLResourceTypeMapping:

1
type GraphQLQueryArguments = Record<string, GraphQLQueryArguments | string>;
2
3
type GraphQLResourceTypeMapping = {
4
  resourceTypeId: string;
5
  graphQLOutputType: string;
6
  graphQLQueryField: string;
7
  graphQLQueryArguments: GraphQLQueryArguments;
8
};

GraphQLResourceTypeMapping would have the following values for the product field:

Property mapping for rendering in the Web app

The Contentful web app displays entries using components that require specific data structures to fill their UI elements.

The mapping between these components and external system data is established using JSON pointers. This mapping is defined in the defaultFieldMapping property of each Resource Type and must adhere to the structure used for mapping the values shown in the entry component:

The definitions of Product Resource Type representations can be found in the src/tools/entities/product.json file, respectively.

Create additional resource type

In our example, we focus on a single Resource Type: Product, because the MockShop API provides only one type: product. If you want to include additional resource types, consider the following:

• Discover more entities available in the third party system.
• Create a new entity file in src/tools/entities/, similar to src/entities/product.json with a Resource Type definition.
• Update the src/tools/import.ts file to import the newly created JSON file.
• Update the resource entities creations script in src/tools/create-resource-entities.ts to include the new type.
• Update the resources by running the creation script: npm run create-resource-entities.
• Build the function and update the bundled version stored in Contentful:

$
npm run build
$
npm run upload