Turn your content types into strongly typed models

Jan Cerman

6 minutes

Delivery API

Download PDF

0% complete

Improve your development experience by using strongly typed models based on your Kontent.ai content types.

Life without strongly typed models

When getting content directly from the Delivery REST API, you receive content items as JSON objects. Your app then needs to parse the JSON to display your content. For example, to access the Headline element in a content item, you’d use a notation like this response.data.item.elements.headline.value.

Here is an example of retrieving, parsing, and displaying a content item.

In real-life scenarios, this approach might be cumbersome because it requires you to remember the JSON structure of your content items, and the codenames of your elements, types, languages, and other entities. To make this easier, use a Delivery SDK (the JS version

or the .NET version

) to map the retrieved content items to their strongly typed models.

Use strongly typed models

This practice has several advantages:

type safety during compile-time
convenience (IntelliSense remembers content type properties for you)
support of type-dependent functionalities

Each model corresponds to a content type in your Kontent.ai project.

Here is the Homepage content type used in the previous TypeScript code example.

The Homepage content type for Hello World — Homepage content type.

A strongly typed model provides type-safe access to:

All elements defined within a specific content type
System fields such as type, workflow, language, and more

The following example is a strongly typed model of the Homepage content type.

TypeScript

/**
 * `CoreContentType` represents the base structure of a content type in Kontent.ai.
 * It provides strongly typed access to system fields such as language, workflow, type, and more.
 *
 * All models are generated by the https://www.npmjs.com/package/@kontent-ai/model-generator
 */
export type Homepage = CoreContentType<
  HomepageElementCodenames,
  {
    /**
     * Headline
     *
     * Type: text
     * Required: false
     * Codename: headline
     * Id: 65abffb4-15c9-9b5e-cb0d-7c36300198fb
     * Guidelines: The main headline of your homepage. It can be different than the name in Kontent. Simple text elements don't allow any formatting.
     */
    readonly headline: Elements.TextElement;
    /**
     * Body text
     *
     * Type: rich_text
     * Required: false
     * Codename: body_text
     * Id: 5dc5b1c4-c3b2-14df-65b5-ff5520110bc3
     * Guidelines: Provide main content for the homepage.
     */
    readonly body_text: Elements.RichTextElement<CoreContentType>;
    /**
     * Picture
     *
     * Type: asset
     * Required: false
     * Codename: picture
     * Id: e1cbc227-f1ee-db9e-1831-de36fa4265ed
     * Guidelines: Choose an image to show above the headline.
     */
    readonly picture: Elements.AssetsElement;
  },
  "homepage"
>;

/**
 * Type representing all available element codenames for Homepage
 */
export type HomepageElementCodenames = "headline" | "body_text" | "picture";

/**
 * Type guard for Homepage
 *
 * Id: 078f37bf-b6ce-4fcb-a1d3-be1966c6b50a
 * Codename: homepage
 */
export function isHomepage(
  item: CoreContentType | undefined | null
): item is Homepage {
  return item?.system?.type === "homepage";
}

Generate models

We recommend that you generate the models using @kontent-ai/model-generator-js

Use the model generator to create strongly typed models from your Kontent.ai project by providing your environment ID.

Shell

npx @kontent-ai/model-generator@latest delivery-sdk --environmentId=x --managementApiKey=x

Get strongly typed content

With your models defined and added to your application, you can use them when retrieving items from Kontent.ai.

TypeScript

import { createDeliveryClient } from "@kontent-ai/delivery-sdk";

// Initializes the Delivery client with `CoreDeliveryClient` type which improves type safety on system fields
// This type is generated by the https://www.npmjs.com/package/@kontent-ai/model-generator
const deliveryClient = createDeliveryClient<CoreDeliveryClient>({
  environmentId: "8d20758c-d74c-4f59-ae04-ee928c0816b7",
});

// Gets an item by codename from Kontent.ai and treats it as a strongly typed model
const homepageItem = (
  await deliveryClient.item<Homepage>("hello_caas_world").toPromise()
).data.item;

// The example above assumes that the item with the codename `hello_caas_world` is of type `Homepage`.
// However, this may not always be the case. To avoid potential runtime errors, it is recommended to
// use generated type guards, such as:
const item = (await deliveryClient.item(`hello_headless_world`).toPromise())
  .data.item;

if (isHomepage(item)) {
  // At this point, the item's type is known, allowing safe and straightforward access to its properties.
  const headline = item.elements.headline.value;
}

A complete example

This code example is equivalent to the first one but maps the retrieved content item to a strongly typed model.

Sign in with your Kontent.ai credentials or sign up for free to unlock the full lesson, track your progress, and access exclusive expert insights and tips!