Use strongly-typed models

November 23, 2022

Jan Cerman

3 min read

Strongly-typed models are programmatic representations of the content types in your Kontent.ai project. They help you map the JSON objects you get from Delivery REST API directly to a model you can use in your code.

The mapping works a little differently for each platform. We recommend that you check the docs of the SDK you're using:

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.

See the code example on https://stackblitz.com/edit/kontent-ai-learn-display-content-without-models

In a more complicated scenario, this approach becomes cumbersome. It forces you to remember the JSON structure of your content items and the codenames of your content elements.

To make this easier, use a Delivery SDK 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

The models are plain classes that don't have any attached behavior or dependency on an external framework. 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.

Assembled Homepage content type for Hello World

To create a content type's representation in code, you need a class with properties representing the individual content elements:

Each property is mapped to its content element's codename either explicitly or using a naming convention. For example, codename body_text becomes property bodyText.
Properties are usually typed using classes provided by the SDK.
Depending on the SDK, simple content elements (like text and number) are sometimes represented using native types (like string and integer).

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

Java
// Tip: Find more about Java SDK at https://kontent.ai/learn/java
import kontent.ai.delivery.Asset;
import kontent.ai.delivery.ContentItemMapping;
import kontent.ai.delivery.ElementMapping;
import kontent.ai.delivery.System;
import java.lang.String;
import java.util.List;

/**
 * This code was generated by a <a href="https://github.com/kontent-ai/java-packages/tree/master/delivery-sdk-generators">kontent-generators-java tool</a>
 *
 * Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
 * For further modifications of the class, create a separate file and extend this class.
 */
@ContentItemMapping("homepage")
public class Homepage {
    @ElementMapping("body_text")
    String bodyText;

    @ElementMapping("headline")
    String headline;

    @ElementMapping("picture")
    List<Asset> picture;

    System system;

    public String getBodyText() {
        return bodyText;
    }

    public void setBodyText(String bodyText) {
        this.bodyText = bodyText;
    }

    public String getHeadline() {
        return headline;
    }

    public void setHeadline(String headline) {
        this.headline = headline;
    }

    public List<Asset> getPicture() {
        return picture;
    }

    public void setPicture(List<Asset> picture) {
        this.picture = picture;
    }

    public System getSystem() {
        return system;
    }

    public void setSystem(System system) {
        this.system = system;
    }
}
// Tip: Find more about Java SDK at https://kontent.ai/learn/java
import kontent.ai.delivery.Asset;
import kontent.ai.delivery.ContentItemMapping;
import kontent.ai.delivery.ElementMapping;
import kontent.ai.delivery.System;
import java.lang.String;
import java.util.List;

/**
 * This code was generated by a <a href="https://github.com/kontent-ai/java-packages/tree/master/delivery-sdk-generators">kontent-generators-java tool</a>
 *
 * Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
 * For further modifications of the class, create a separate file and extend this class.
 */
@ContentItemMapping("homepage")
public class Homepage {
    @ElementMapping("body_text")
    String bodyText;

    @ElementMapping("headline")
    String headline;

    @ElementMapping("picture")
    List<Asset> picture;

    System system;

    public String getBodyText() {
        return bodyText;
    }

    public void setBodyText(String bodyText) {
        this.bodyText = bodyText;
    }

    public String getHeadline() {
        return headline;
    }

    public void setHeadline(String headline) {
        this.headline = headline;
    }

    public List<Asset> getPicture() {
        return picture;
    }

    public void setPicture(List<Asset> picture) {
        this.picture = picture;
    }

    public System getSystem() {
        return system;
    }

    public void setSystem(System system) {
        this.system = system;
    }
}

C#
// This code was generated by a kontent-generators-net tool 
// (see https://github.com/kontent-ai/model-generator-net).
// 
// Changes to this file may cause incorrect behavior and will be lost if the code is regenerated. 
// For further modifications of the class, create a separate file with the partial class.

using System;
using System.Collections.Generic;
using Kontent.Ai.Delivery.Abstractions;

namespace KontentAiModels
{
    public partial class Homepage
    {
        public const string Codename = "homepage";
        public const string BodyTextCodename = "body_text";
        public const string HeadlineCodename = "headline";
        public const string PictureCodename = "picture";

        public IRichTextContent BodyText { get; set; }
        public string Headline { get; set; }
        public IEnumerable<IAsset> Picture { get; set; }
        public IContentItemSystemAttributes System { get; set; }
    }
}
// This code was generated by a kontent-generators-net tool 
// (see https://github.com/kontent-ai/model-generator-net).
// 
// Changes to this file may cause incorrect behavior and will be lost if the code is regenerated. 
// For further modifications of the class, create a separate file with the partial class.

using System;
using System.Collections.Generic;
using Kontent.Ai.Delivery.Abstractions;

namespace KontentAiModels
{
    public partial class Homepage
    {
        public const string Codename = "homepage";
        public const string BodyTextCodename = "body_text";
        public const string HeadlineCodename = "headline";
        public const string PictureCodename = "picture";

        public IRichTextContent BodyText { get; set; }
        public string Headline { get; set; }
        public IEnumerable<IAsset> Picture { get; set; }
        public IContentItemSystemAttributes System { get; set; }
    }
}

TypeScript
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { Elements, IContentItem } from '@kontent-ai/delivery-sdk';

/**
 * Generated by '@kontent-ai/model-generator@5.0.0' at 'Thu, 14 Jul 2022 13:58:53 GMT'
 *
 * Homepage
 * Id: b0c0f9c2-ffb6-4e62-bac9-34e14172dd8c
 * Codename: homepage
 */
export type Homepage = IContentItem<{
     headline: Elements.TextElement;
     bodyText: Elements.RichTextElement;
     picture: Elements.AssetsElement;
}>;
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { Elements, IContentItem } from '@kontent-ai/delivery-sdk';

/**
 * Generated by '@kontent-ai/model-generator@5.0.0' at 'Thu, 14 Jul 2022 13:58:53 GMT'
 *
 * Homepage
 * Id: b0c0f9c2-ffb6-4e62-bac9-34e14172dd8c
 * Codename: homepage
 */
export type Homepage = IContentItem<{
     headline: Elements.TextElement;
     bodyText: Elements.RichTextElement;
     picture: Elements.AssetsElement;
}>;

Generate models

We recommend that you generate the models using the TypeScript/JavaScript model generator.

We recommend that you generate the models using the .NET model generator.

We recommend that you generate the models using the Java model generator.

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

Java
// Find instructions on using the Java model generator at https://github.com/kontent-ai/java-packages/tree/master/delivery-sdk-generators
import com.squareup.javapoet.JavaFile
import kontent.ai.delivery.DeliveryClient
import kontent.ai.delivery.DeliveryOptions
import kontent.ai.delivery.generators.CodeGenerator

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath('ai.kontent:kontent-delivery-generators:latest.release')
    }
}

// showcase task
task generateModels {
    doLast {

        // The most complex solution, you could configure the client as you want
        // i.e. set preview API key
        DeliveryOptions options = new DeliveryOptions();
        options.setProjectId("975bf280-fd91-488c-994c-2f04416e5ee3");
        DeliveryClient client = new DeliveryClient(options);

        CodeGenerator generator = new CodeGenerator(
            options.getProjectId(),
            'ai.kontent.test.springapp.models',
            file('src/main/java')
        );
        List<JavaFile> sources = generator.generateSources(client);
        generator.writeSources(sources);
    }
}
// Find instructions on using the Java model generator at https://github.com/kontent-ai/java-packages/tree/master/delivery-sdk-generators
import com.squareup.javapoet.JavaFile
import kontent.ai.delivery.DeliveryClient
import kontent.ai.delivery.DeliveryOptions
import kontent.ai.delivery.generators.CodeGenerator

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath('ai.kontent:kontent-delivery-generators:latest.release')
    }
}

// showcase task
task generateModels {
    doLast {

        // The most complex solution, you could configure the client as you want
        // i.e. set preview API key
        DeliveryOptions options = new DeliveryOptions();
        options.setProjectId("975bf280-fd91-488c-994c-2f04416e5ee3");
        DeliveryClient client = new DeliveryClient(options);

        CodeGenerator generator = new CodeGenerator(
            options.getProjectId(),
            'ai.kontent.test.springapp.models',
            file('src/main/java')
        );
        List<JavaFile> sources = generator.generateSources(client);
        generator.writeSources(sources);
    }
}

shell
npm i @kontent-ai/model-generator -g

kontent-generate --projectId=8d20758c-d74c-4f59-ae04-ee928c0816b7 --addTimestamp=false --nameResolver=camelCase --sdkType=delivery --apiKey=<YOUR_MANAGEMENT_API_KEY>
npm i @kontent-ai/model-generator -g

kontent-generate --projectId=8d20758c-d74c-4f59-ae04-ee928c0816b7 --addTimestamp=false --nameResolver=camelCase --sdkType=delivery --apiKey=<YOUR_MANAGEMENT_API_KEY>

shell
dotnet tool install -g Kontent.Ai.ModelGenerator
KontentModelGenerator --projectid 8d20758c-d74c-4f59-ae04-ee928c0816b7 --withtypeprovider true --structuredmodel true
dotnet tool install -g Kontent.Ai.ModelGenerator
KontentModelGenerator --projectid 8d20758c-d74c-4f59-ae04-ee928c0816b7 --withtypeprovider true --structuredmodel true

shell
npm i @kontent-ai/model-generator -g

kontent-generate --projectId=8d20758c-d74c-4f59-ae04-ee928c0816b7 --addTimestamp=false --nameResolver=camelCase --sdkType=delivery --apiKey=<YOUR_MANAGEMENT_API_KEY>
npm i @kontent-ai/model-generator -g

kontent-generate --projectId=8d20758c-d74c-4f59-ae04-ee928c0816b7 --addTimestamp=false --nameResolver=camelCase --sdkType=delivery --apiKey=<YOUR_MANAGEMENT_API_KEY>

Get strongly typed content

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

Java
// Tip: Find more about Java SDK at https://kontent.ai/learn/java
import kontent.ai.delivery.*;

// Initializes a DeliveryClient
DeliveryClient client = new DeliveryClient("8d20758c-d74c-4f59-ae04-ee928c0816b7");

// Create strongly typed models according to https://kontent.ai/learn/strongly-typed-models
// Registers the model class for navigation items
client.registerType(Homepage.class);

CompletionStage<Homepage> homepageResult = client.getItem("hello_caas_world", Homepage.class);
// Use homepageResult
// homepageResult.thenAccept(homepage -> System.out.println(homepage.getHeadline())
// Tip: Find more about Java SDK at https://kontent.ai/learn/java
import kontent.ai.delivery.*;

// Initializes a DeliveryClient
DeliveryClient client = new DeliveryClient("8d20758c-d74c-4f59-ae04-ee928c0816b7");

// Create strongly typed models according to https://kontent.ai/learn/strongly-typed-models
// Registers the model class for navigation items
client.registerType(Homepage.class);

CompletionStage<Homepage> homepageResult = client.getItem("hello_caas_world", Homepage.class);
// Use homepageResult
// homepageResult.thenAccept(homepage -> System.out.println(homepage.getHeadline())

C#
// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net
using Kontent.Ai.Delivery;
using KontentAiModels;

// Creates an instance of the delivery client
// ProTip: Use DI for this in your apps https://kontent.ai/learn/net-register-client
IDeliveryClient client = DeliveryClientBuilder
      .WithProjectId("8d20758c-d74c-4f59-ae04-ee928c0816b7")
      .Build();

// Gets a content item by codename and maps it to the item's strongly typed model
IDeliveryItemResponse<Homepage> response = await client.GetItemAsync<Homepage>("hello_caas_world");

var homepage = response.Item;
// Use homepage
// Console.WriteLine(homepage.Headline);
// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net
using Kontent.Ai.Delivery;
using KontentAiModels;

// Creates an instance of the delivery client
// ProTip: Use DI for this in your apps https://kontent.ai/learn/net-register-client
IDeliveryClient client = DeliveryClientBuilder
      .WithProjectId("8d20758c-d74c-4f59-ae04-ee928c0816b7")
      .Build();

// Gets a content item by codename and maps it to the item's strongly typed model
IDeliveryItemResponse<Homepage> response = await client.GetItemAsync<Homepage>("hello_caas_world");

var homepage = response.Item;
// Use homepage
// Console.WriteLine(homepage.Headline);

TypeScript
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { createDeliveryClient } from '@kontent-ai/delivery-sdk';

import { Homepage } from './models/homepage';

// Initializes the Delivery client and registers your model in type resolvers
const deliveryClient = createDeliveryClient({
    environmentId: '8d20758c-d74c-4f59-ae04-ee928c0816b7',
});

var homepage: Homepage;

// Gets an item by codename from Kontent.ai and maps it to a strongly typed model
const response = await deliveryClient.item<Homepage>('hello_caas_world')
  .toPromise();

homepage = response.data.item;
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { createDeliveryClient } from '@kontent-ai/delivery-sdk';

import { Homepage } from './models/homepage';

// Initializes the Delivery client and registers your model in type resolvers
const deliveryClient = createDeliveryClient({
    environmentId: '8d20758c-d74c-4f59-ae04-ee928c0816b7',
});

var homepage: Homepage;

// Gets an item by codename from Kontent.ai and maps it to a strongly typed model
const response = await deliveryClient.item<Homepage>('hello_caas_world')
  .toPromise();

homepage = response.data.item;

A complete example

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

See the code example on https://stackblitz.com/edit/kontent-ai-learn-display-content-with-models

What's next?

You'll often have to define how your application resolves rich text elements containing assets, links, components, and other content items. For more advanced examples of using strongly typed models, see our sample applications.

Is this page helpful?

Yes No