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 to 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

In order to retrieve content items from a project, you will need the project ID. Your project is the primary organizational unit in Kentico Cloud. Every project is uniquely identified by an ID you can use to tell the Delivery API where to look for content. For example, a project ID might 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");

// 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');

const deliveryClient = new KenticoCloud.DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3'
});

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

const deliveryClient = new DeliveryClient({
  projectId: '975bf280-fd91-488c-994c-2f04416e5ee3'
});

deliveryClient.items<ContentItem>()
    .getObservable()
    .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.*;
import com.kenticocloud.delivery_rx.*;

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

// Prepares the DeliveryService configuration object
String projectId = "975bf280-fd91-488c-994c-2f04416e5ee3";
IDeliveryConfig config = DeliveryConfig.newConfig(projectId);

// Initializes a DeliveryService for Java projects
IDeliveryService deliveryService = new DeliveryService(config);

// Gets all content items using a simple request
List<ContentItem> items = deliveryService.<ContentItem>items()
    .get()
    .getItems();

// Gets all content items using RxJava2
deliveryService.<ContentItem>items()
    .getObservable()
    .subscribe(new Observer<DeliveryItemListingResponse<ContentItem>>() {
        @Override
        public void onSubscribe(Disposable d) {
        }

        @Override
        public void onNext(DeliveryItemListingResponse<ContentItem> response) {
            // Gets the content items
            List<ContentItem> items = response.getItems();
        }

        @Override
        public void onError(Throwable e) {
        }

        @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 content 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');

// Create strongly typed models according to https://github.com/Enngage/kentico-cloud-js/blob/master/doc/delivery.md#creating-models
class Article extends KenticoCloud.ContentItem {
    constructor() {
        super();
    }
}

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

deliveryClient.items()
    .type('article')
    .getObservable()
    .subscribe(response => console.log(response));
import { ContentItem, DeliveryClient, Fields, 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
export class Article extends ContentItem {
    public title: Fields.TextField;
    public summary: Fields.TextField;
    public post_date: Fields.DateTimeField;
    public teaser_image: Fields.AssetsField;
    public related_articles: 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));
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.*;
import com.kenticocloud.delivery_rx.*;

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

// Generate strongly-typed models via https://github.com/Kentico/cloud-generators-java
// Prepares an array to hold the strongly-typed models
List<TypeResolver<?>> typeResolvers = new ArrayList<>();

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

// Prepares the DeliveryService configuration object
String projectId = "975bf280-fd91-488c-994c-2f04416e5ee3";
IDeliveryConfig config = DeliveryConfig.newConfig(projectId)
    .withTypeResolvers(typeResolvers);

// Initializes a DeliveryService for Java projects
IDeliveryService deliveryService = new DeliveryService(config);

// Gets all articles using a simple request
List<ContentItem> items = deliveryService.<ContentItem>items()
    .equalsFilter("system.type", "article")
    .get()
    .getItems();

// Gets all articles using RxJava2
deliveryService.<ContentItem>items()
    .equalsFilter("system.type", "article")
    .getObservable()
    .subscribe(new Observer<DeliveryItemListingResponse<ContentItem>>() {
        @Override
        public void onSubscribe(Disposable d) {
        }

        @Override
        public void onNext(DeliveryItemListingResponse<ContentItem> response) {
            // Gets the articles
            List<ContentItem> items = response.getItems();
        }

        @Override
        public void onError(Throwable e) {
        }

        @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');

// Create strongly typed models according to https://github.com/Enngage/kentico-cloud-js/blob/master/doc/delivery.md#creating-models
class Article extends KenticoCloud.ContentItem {
    constructor() {
        super();
    }
}

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

deliveryClient.items()
    .type('article')
    .limitParameter(3)
    .orderParameter('system.last_modified', KenticoCloud.SortOrder.desc)
    .getObservable()
    .subscribe(response => console.log(response));
import { ContentItem, DeliveryClient, Fields, SortOrder, 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
export class Article extends ContentItem {
    public title: Fields.TextField;
    public summary: Fields.TextField;
    public post_date: Fields.DateTimeField;
    public teaser_image: Fields.AssetsField;
    public related_articles: Article[];
}

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

deliveryClient.items<Article>()
    .type('article')
    .limitParameter(3)
    .orderParameter('system.last_modified', SortOrder.desc)
    .getObservable()
    .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.*;
import com.kenticocloud.delivery_rx.*;

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

// Generate strongly-typed models via https://github.com/Kentico/cloud-generators-java
// Prepares an array to hold the strongly-typed models
List<TypeResolver<?>> typeResolvers = new ArrayList<>();

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

// Prepares the DeliveryService configuration object
String projectId = "975bf280-fd91-488c-994c-2f04416e5ee3";
IDeliveryConfig config = DeliveryConfig.newConfig(projectId)
    .withTypeResolvers(typeResolvers);

// Initializes a DeliveryService for Java projects
IDeliveryService deliveryService = new DeliveryService(config);

// Gets the 3 latest articles ordered by their last modified time using a simple request
List<Article> articles = deliveryService.<Article>items()
    .equalsFilter("system.type", "article")
    .orderParameter("system.last_modified", OrderType.Desc)
    .limitParameter(3)
    .get()
    .getItems();

// Gets the 3 latest articles ordered by their last modified time using RxJava2
deliveryService.<Article>items()
    .equalsFilter("system.type", "article")
    .orderParameter("system.last_modified", OrderType.Desc)
    .limitParameter(3)
    .getObservable()
    .subscribe(new Observer<DeliveryItemListingResponse<Article>>() {
        @Override
        public void onSubscribe(Disposable d) {
        }

        @Override
        public void onNext(DeliveryItemListingResponse<Article> response) {
            // Gets the mapped articles
            List<Article> articles = response.getItems();
        }

        @Override
        public void onError(Throwable e) {
        }

        @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.