Getting content

Learn how to retrieve content from your Kentico Cloud project. This tutorial walks you through retrieving a list of specific content items in a given order.

While your copywriters write articles and add finishing touches on the content in your project, you can deliver that content to web and mobile applications via an API. In this tutorial, you'll learn how to retrieve your content from Kentico Cloud using the Delivery API.

The Delivery API is a read-only REST API that can serve your content in two modes: public and preview. In public mode, you can only retrieve content that is published and publicly available. In preview mode, you can retrieve published as well as any unpublished content. This tutorial covers using the Delivery API in public mode, in which you don't need to authenticate your requests.

Let's dive in and see what you need to retrieve a list of specific content items, such as articles.

Getting content items

First, let's go over the things you need in order to retrieve content items from a project.

Your project is the primary organizational unit in Kentico Cloud. Every project is uniquely identified by an ID. You will need the Project ID to tell the Delivery API where to look for content. For example, a project ID can look like this 975bf280-fd91-488c-994c-2f04416e5ee3.

To get the ID of your project:

  1. In Kentico Cloud, choose a project.
  2. From the app menu, choose Project settings.
  3. Under Development, choose API keys.
  4. In the Project ID box, click Copy to clipboard.

With the Project ID, you can now make queries to the Delivery API using a URL such as https://deliver.kenticocloud.com/<YOUR_PROJECT_ID>/items.

curl --request GET \
  --url 'https://deliver.kenticocloud.com/975bf280-fd91-488c-994c-2f04416e5ee3/items'
  --header 'content-type: application/json'
using KenticoCloud.Delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

// Generate strongly typed models via https://github.com/Kentico/cloud-generators-net
// Calling with the <object> generic parameter produces strongly-typed objects, based on "system.type"
DeliveryItemListingResponse<object> response = await client.GetItemsAsync<object>();

var items = response.Items;
const KenticoCloud = require('kentico-cloud-delivery-typescript-sdk');

class Article extends KenticoCloud.ContentItem {
    constructor() {
        super();
    }
}

const config = new KenticoCloud.DeliveryClientConfig('975bf280-fd91-488c-994c-2f04416e5ee3', 
    [ new KenticoCloud.TypeResolver('article', () => new Article()) 
]);

const deliveryClient = new KenticoCloud.DeliveryClient(config);

deliveryClient.items()
    .get()
    .subscribe(response => console.log(response));
import { DeliveryClient, SortOrder, TypeResolver, ContentItem } from 'kentico-cloud-delivery';

// Create strongly typed models according to https://github.com/Enngage/KenticoCloudDeliveryTypeScriptSDK/wiki/TypeScript-SDK#creating-models
import { Article } from './models/article';

const deliveryClient = new DeliveryClient({
  projectId: '975bf280-fd91-488c-994c-2f04416e5ee3',
  typeResolvers: [
    new TypeResolver('article', () => new Article)
  ]
});

deliveryClient.items<ContentItem>()
    .getObservable()
    .subscribe(response => console.log(response));
const KenticoCloud = require('kentico-cloud-delivery-node-sdk');

class Article extends KenticoCloud.ContentItem {
    constructor() {
        super();
    }
}

const config = new KenticoCloud.DeliveryClientConfig('975bf280-fd91-488c-994c-2f04416e5ee3', 
    [ new KenticoCloud.TypeResolver('article', () => new Article()) 
]);

const deliveryClient = new KenticoCloud.DeliveryNodeClient(config);

deliveryClient.items()
    .get()
    .subscribe(response => console.log(response));
import com.kenticocloud.delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

List<NameValuePair> params = DeliveryParameterBuilder.params()
    .build();

ContentItemsListingResponse listingResponse = client.getItems();
import com.kenticocloud.delivery_core.config.DeliveryConfig;
import com.kenticocloud.delivery_core.elements.AssetsElement;
import com.kenticocloud.delivery_core.elements.DateTimeElement;
import com.kenticocloud.delivery_core.elements.TextElement;
import com.kenticocloud.delivery_core.interfaces.item.item.IContentItem;
import com.kenticocloud.delivery_core.models.common.OrderType;
import com.kenticocloud.delivery_core.models.item.ContentItem;
import com.kenticocloud.delivery_core.models.item.DeliveryItemListingResponse;
import com.kenticocloud.delivery_core.models.item.ElementMapping;
import com.kenticocloud.delivery_core.models.item.TypeResolver;
import com.kenticocloud.delivery_core.services.IDeliveryService;
import com.kenticocloud.delivery_rx.DeliveryService;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

import io.reactivex.Observer;
import io.reactivex.disposables.Disposable;
import io.reactivex.functions.Function;

public class ListContentItems{

    public void Example() {
      
        List<TypeResolver<?>> typeResolvers = new ArrayList<>();
        
        // Initialize DeliveryService for Java projects
        IDeliveryService deliveryService = new DeliveryService(new DeliveryConfig("975bf280-fd91-488c-994c-2f04416e5ee3", typeResolvers).setThrowExceptionForUnknownTypes(false));

        // Use simple request to get data
        List<ContentItem> items = deliveryService.<ContentItem>items()
                .get()
                .getItems();

        // Use RxJava2 to get the data
        deliveryService.<ContentItem>items()
                .getObservable()
                .subscribe(new Observer<DeliveryItemListingResponse<ContentItem>>() {
                    @Override
                    public void onSubscribe(Disposable d) {
                    }

                    @Override
                    public void onNext(DeliveryItemListingResponse<ContentItem> response) {

                        // Get your content items
                        List<ContentItem> items = response.getItems();

                        // Get first item
                        ContentItem firstItem = items.get(0);

                        // Print the first item
                        System.out.println(firstItem.getSystem().getName());
                    }

                    @Override
                    public void onError(Throwable e) {
	                      // Print the error message
                        System.out.println(e.getMessage());
                    }

                    @Override
                    public void onComplete() {
                    }
                });
    }
}
<?php

// Defined by Composer to include required libraries
require __DIR__ . '/vendor/autoload.php';

use KenticoCloud\Delivery\DeliveryClient;

$client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3');

$items = $client->getItems();
import KenticoCloud

let client = DeliveryClient.init(projectId: "975bf280-fd91-488c-994c-2f04416e5ee3")

// Note: Using 'items' as custom query returns all items,
// but to map them to a single model, a filter is needed.
let customQuery = "items?system.type=article"

// More about strongly-typed models https://github.com/Kentico/cloud-sdk-swift#using-strongly-typed-models
client.getItems(modelType: Article.self, customQuery: customQuery) { (isSuccess, itemsResponse, error) in
    if isSuccess {
        if let articles = itemsResponse?.items {
            // Use your items here
        }
    } else {
        if let error = error {
            print(error)
        }
    }
}

Calling the /items endpoint gives you all content items from the specified project in the form of a paged listing response, returned as JSON. You can learn more about the listing response in our API reference.

Paging the results

If you don't need all content items at once, you can tinker with the paging by specifying the limit and skip query parameters.

For example, calling the /items endpoint with the limit=3&skip=6 query parameters sets the page size to 3 and gives you the third page.

Filtering content items

Now that you can get all content items from your project, you need to filter them to get only a specific few. In this example, you'll retrieve articles. These are the content items based on the Article content type.

To move any further, you need to find the codename of the Article content type.

Quick facts about codenames

Codenames are case sensitive identifiers of objects in Kentico Cloud. They are generated by the system each time the name of an object is updated. This also means that you cannot change codenames directly.

You can copy codenames by clicking the codename button {#} near the name of a content item, content type, content element, or other objects in your project.

Example: Displaying the codename of the *Article* content type.

Example: Displaying the codename of the Article content type.

Once you have the codename (in this case, article) you can use it to filter the retrieved content items by content type.

The information about a content item's type is stored in the System object within the type attribute. The System object contains metadata about the content item such as last modification date, the item's location in sitemap, content type the item is based on, language, etc.

"system": {
    "id": "cf106f4e-30a4-42ef-b313-b8ea3fd3e5c5",
    "name": "Coffee Beverages Explained",
    "codename": "coffee_beverages_explained",
    "language": "en-US",
    "type": "article",
    "sitemap_locations": [
        "articles"
    ],
    "last_modified": "2016-10-27T11:14:58.9229067Z"
}

So, to filter the content items by type, you need to compare the value in the type system attribute to article using the following notation: system.type=article. Any content items that are not based on the Article content type will be omitted from the response.

curl --request GET \
  --url 'https://deliver.kenticocloud.com/975bf280-fd91-488c-994c-2f04416e5ee3/items?system.type=article'
  --header 'content-type: application/json'
using KenticoCloud.Delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

// Generate strongly typed models via https://github.com/Kentico/cloud-generators-net
DeliveryItemListingResponse<Article> response = await client.GetItemsAsync<Article>(
    new EqualsFilter("system.type", "article"),
);

var items = response.Items;
const KenticoCloud = require('kentico-cloud-delivery-typescript-sdk');

class Article extends KenticoCloud.ContentItem {
    constructor() {
        super();
    }
}

const config = new KenticoCloud.DeliveryClientConfig('975bf280-fd91-488c-994c-2f04416e5ee3', 
    [ new KenticoCloud.TypeResolver('article', () => new Article()) 
]);

const deliveryClient = new KenticoCloud.DeliveryClient(config);

deliveryClient.items()
    .type('article')
    .get()
    .subscribe(response => console.log(response));
import { ContentItem, DeliveryClient, TypeResolver } from 'kentico-cloud-delivery';

// Create strongly typed models according to https://github.com/Enngage/kentico-cloud-js/blob/master/doc/delivery.md#creating-models
import { Article } from './models/article';

const deliveryClient = new DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3',
    typeResolvers: [
        new TypeResolver('article', () => new Article)
    ]
});

deliveryClient.items<Article>()
    .type('article')
    .getObservable()
    .subscribe(response => console.log(response));
const KenticoCloud = require('kentico-cloud-delivery-node-sdk');

class Article extends KenticoCloud.ContentItem {
    constructor() {
        super();
    }
}

const config = new KenticoCloud.DeliveryClientConfig('975bf280-fd91-488c-994c-2f04416e5ee3', 
    [ new KenticoCloud.TypeResolver('article', () => new Article()) 
]);

const deliveryClient = new KenticoCloud.DeliveryNodeClient(config);

deliveryClient.items()
    .type('article')
    .get()
    .subscribe(response => console.log(response));
import com.kenticocloud.delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

List<NameValuePair> params = DeliveryParameterBuilder.params()
    .filterEquals("system.type", "article")
    .build();

// Generate strongly typed models via https://github.com/Kentico/cloud-generators-java
List<ArticleItem> items = client.getItems(ArticleItem.class);
import com.kenticocloud.delivery_core.config.DeliveryConfig;
import com.kenticocloud.delivery_core.elements.AssetsElement;
import com.kenticocloud.delivery_core.elements.DateTimeElement;
import com.kenticocloud.delivery_core.elements.TextElement;
import com.kenticocloud.delivery_core.interfaces.item.item.IContentItem;
import com.kenticocloud.delivery_core.models.common.OrderType;
import com.kenticocloud.delivery_core.models.item.ContentItem;
import com.kenticocloud.delivery_core.models.item.DeliveryItemListingResponse;
import com.kenticocloud.delivery_core.models.item.ElementMapping;
import com.kenticocloud.delivery_core.models.item.TypeResolver;
import com.kenticocloud.delivery_core.services.IDeliveryService;
import com.kenticocloud.delivery_rx.DeliveryService;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

import io.reactivex.Observer;
import io.reactivex.disposables.Disposable;
import io.reactivex.functions.Function;

public class ListContentItems{

    // Prepare strongly typed model
    public final class Article extends ContentItem {

        public static final String TYPE = "article";

        @ElementMapping("summary")
        public TextElement summary;

        @ElementMapping("title")
        public TextElement title;

        @ElementMapping("teaser_image")
        public AssetsElement teaserImage;

        @ElementMapping("post_date")
        public DateTimeElement postDate;
    }

    public void Example() {

        // Prepare array to hold all your type resolvers
        List<TypeResolver<?>> typeResolvers = new ArrayList<>();

        // Register type resolver
        typeResolvers.add(new TypeResolver<>(Article.TYPE, new Function<Void, Article>() {
            @Override
            public Article apply(Void input) {
                return new Article();
            }
        }));

        // Initialize DeliveryService for Java projects
        IDeliveryService deliveryService = new DeliveryService(new DeliveryConfig("975bf280-fd91-488c-994c-2f04416e5ee3", typeResolvers));

        // Use simple request to get data
        List<Article> articles = deliveryService.<Article>items()
                .equalsFilter("system.type", "article")
                .get()
                .getItems();

        // Use RxJava2 to get the data
        deliveryService.<Article>items()
                .equalsFilter("system.type", "article")
                .getObservable()
                .subscribe(new Observer<DeliveryItemListingResponse<Article>>() {
                    @Override
                    public void onSubscribe(Disposable d) {
                    }

                    @Override
                    public void onNext(DeliveryItemListingResponse<Article> response) {

                        // Get your mapped articles
                        List<Article> articles = response.getItems();

                        // Get first article
                        Article firstArticle = articles.get(0);

                        // Print the Title of first article
                        System.out.println(firstArticle.title.getValue());
                    }

                    @Override
                    public void onError(Throwable e) {
	                      // Print the error message
                        System.out.println(e.getMessage());
                    }

                    @Override
                    public void onComplete() {
                    }
                });
    }
}
<?php

// Defined by Composer to include required libraries
require __DIR__ . '/vendor/autoload.php';

use KenticoCloud\Delivery\DeliveryClient;
use KenticoCloud\Delivery\QueryParams;

$client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3');

$items = $client->getItems((new QueryParams())
            ->equals('system.type', 'article')));
import KenticoCloud

let client = DeliveryClient.init(projectId: "975bf280-fd91-488c-994c-2f04416e5ee3")

let customQuery = "items?system.type=article"

// More about strongly-typed models https://github.com/Kentico/cloud-sdk-swift#using-strongly-typed-models
client.getItems(modelType: Article.self, customQuery: customQuery) { (isSuccess, itemsResponse, error) in
    if isSuccess {
        if let articles = itemsResponse?.items {
            // Use your items here
        }
    } else {
        if let error = error {
            print(error)
        }
    }
}

Note: The value comparison is done using the equals operator (=). To learn more about other filtering operators, such as less than ([lt]), greater than ([gt]), range ([range]) and more, see content filtering in our API reference.

Ordering content items

The Delivery API sorts content items alphabetically by their codenames by default. But with content like articles, you usually want to retrieve and display them in a certain order and get, for example, only the 3 latest articles from your project.

When getting lists of content items, you can specify their order by using the order query parameter. The value of the order query parameter must be in the following format: <AttributeToOrderBy>[<asc|desc>]. Where the AttributeToOrderBy value specifies either a System attribute (such as system.type) or a content element within a content item (such as elements.title). For instance, if you don't specify the order when retrieving content, it is the equivalent of adding order=system.codename[asc] to your query.

To get the 3 latest articles from your project, you need to provide the following query parameters:

  • system.type=article – specifies the content type of the content items.
  • limit=3 – sets the page size (that is the number of content items to return).
  • order=system.last_modified[desc] – sorts the content items by last modification date in descending order.
curl --request GET \
  --url 'https://deliver.kenticocloud.com/975bf280-fd91-488c-994c-2f04416e5ee3/items?system.type=article&limit=3&order=system.last_modified[desc]'
  --header 'content-type: application/json'
using KenticoCloud.Delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

// Generate strongly typed models via https://github.com/Kentico/cloud-generators-net
DeliveryItemListingResponse<Article> response = await client.GetItemsAsync<Article>(
    new EqualsFilter("system.type", "article"),
    new LimitParameter(3),
    new OrderParameter("system.last_modified", SortOrder.Descending)
);

var items = response.Items;
const KenticoCloud = require('kentico-cloud-delivery-typescript-sdk');

class Article extends KenticoCloud.ContentItem {
    constructor() {
        super();
    }
}

const config = new KenticoCloud.DeliveryClientConfig('975bf280-fd91-488c-994c-2f04416e5ee3', 
    [ new KenticoCloud.TypeResolver('article', () => new Article()) 
]);

const deliveryClient = new KenticoCloud.DeliveryClient(config);

deliveryClient.items()
    .type('article')
    .limitParameter(3)
    .orderParameter('system.last_modification', KenticoCloud.SortOrder.desc)
    .get()
    .subscribe(response => console.log(response));
import { ContentItem, DeliveryClient, TypeResolver, SortOrder } from 'kentico-cloud-delivery';

// Create strongly typed models according to https://github.com/Enngage/kentico-cloud-js/blob/master/doc/delivery.md#creating-models
import { Article } from './models/article';

const deliveryClient = new DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3',
    typeResolvers: [
        new TypeResolver('article', () => new Article)
    ]
});

deliveryClient.items()
    .type('article')
    .limitParameter(3)
    .orderParameter('system.last_modified', KenticoCloud.SortOrder.desc)
    .getObservable()
    .subscribe(response => console.log(response));
const KenticoCloud = require('kentico-cloud-delivery-node-sdk');

class Article extends KenticoCloud.ContentItem {
    constructor() {
        super();
    }
}

const config = new KenticoCloud.DeliveryNodeClientConfig('975bf280-fd91-488c-994c-2f04416e5ee3', 
    [ new KenticoCloud.TypeResolver('article', () => new Article()) 
]);

const deliveryClient = new KenticoCloud.DeliveryClient(config);

deliveryClient.items()
    .type('article')
    .limitParameter(3)
    .orderParameter('system.last_modification', KenticoCloud.SortOrder.desc)
    .get()
    .subscribe(response => console.log(response));
import com.kenticocloud.delivery;

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

List<NameValuePair> params = DeliveryParameterBuilder.params()
    .filterEquals("system.type", "article")
    .page(null, 3)
    .orderByDesc("system.last_modified")
    .build();

// Generate strongly typed models via https://github.com/Kentico/cloud-generators-java
List<ArticleItem> items = client.getItems(ArticleItem.class, params);
import com.kenticocloud.delivery_core.config.DeliveryConfig;
import com.kenticocloud.delivery_core.interfaces.item.item.IContentItem;
import com.kenticocloud.delivery_core.models.common.OrderType;
import com.kenticocloud.delivery_core.models.item.ContentItem;
import com.kenticocloud.delivery_core.models.item.DeliveryItemListingResponse;
import com.kenticocloud.delivery_core.models.item.ElementMapping;
import com.kenticocloud.delivery_core.models.item.TypeResolver;
import com.kenticocloud.delivery_core.services.IDeliveryService;
import com.kenticocloud.delivery_rx.DeliveryService;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

import io.reactivex.Observer;
import io.reactivex.disposables.Disposable;
import io.reactivex.functions.Function;

public class ListContentItems{

    // Prepare strongly typed model
    public final class Article extends ContentItem {

        public static final String TYPE = "article";
    }

    public void Example() {

        // Prepare array to hold all your type resolvers
        List<TypeResolver<?>> typeResolvers = new ArrayList<>();

        // Register type resolver
        typeResolvers.add(new TypeResolver<>(Article.TYPE, new Function<Void, Article>() {
            @Override
            public Article apply(Void input) {
                return new Article();
            }
        }));

        // Initialize DeliveryService for Java projects
        IDeliveryService deliveryService = new DeliveryService(new DeliveryConfig("975bf280-fd91-488c-994c-2f04416e5ee3", typeResolvers));

        // Use simple request to get data
        List<Article> articles = deliveryService.<Article>items()
                .equalsFilter("system.type", "article")
                .limitParameter(3)
                .orderParameter("system.last_modified", OrderType.Desc)
                .get()
                .getItems();

        // Use RxJava2 to get the data
        deliveryService.<Article>items()
                .equalsFilter("system.type", "article")
                .limitParameter(3)
                .orderParameter("system.last_modified", OrderType.Desc)
                .getObservable()
                .subscribe(new Observer<DeliveryItemListingResponse<Article>>() {
                    @Override
                    public void onSubscribe(Disposable d) {
                    }

                    @Override
                    public void onNext(DeliveryItemListingResponse<Article> response) {

                        // Get your mapped articles
                        List<Article> articles = response.getItems();

                        // Get first article
                        Article firstArticle = articles.get(0);

                        // Print the Title of first article
                        System.out.println(firstArticle.title.getValue());
                    }

                    @Override
                    public void onError(Throwable e) {
	                      // Print the error message
                        System.out.println(e.getMessage());
                    }

                    @Override
                    public void onComplete() {
                    }
                });
    }
}
<?php

// Defined by Composer to include required libraries
require __DIR__ . '/vendor/autoload.php';

use KenticoCloud\Delivery\DeliveryClient;
use KenticoCloud\Delivery\QueryParams;

$client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3');

$items = $client->getItems((new QueryParams())
            ->equals('system.type', 'article')
            ->limit(3)
            ->orderDesc('system.last_modified'));
import KenticoCloud

let client = DeliveryClient.init(projectId: "975bf280-fd91-488c-994c-2f04416e5ee3")

let customQuery = "items?system.type=article&limit=3&order=system.last_modified[desc]"

// More about strongly-typed models https://github.com/Kentico/cloud-sdk-swift#using-strongly-typed-models
client.getItems(modelType: Article.self, customQuery: customQuery) { (isSuccess, itemsResponse, error) in
    if isSuccess {
        if let articles = itemsResponse?.items {
            // Use your items here
        }
    } else {
        if let error = error {
            print(error)
        }
    }
}

What's next?

This tutorial showed you how to get specific content from your Kentico Cloud project by filtering and sorting. Besides retrieving content items, you can also query the Delivery API to get content types, content elements, and taxonomy groups. Everything's described in our API reference.

To learn more about using the Delivery API, check out the following articles:

Got questions? Ask our support team by using the blue chat button in the bottom-right corner.

Getting content

Learn how to retrieve content from your Kentico Cloud project. This tutorial walks you through retrieving a list of specific content items in a given order.