Getting content

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.

Table of contents

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:

In Kentico Cloud, choose a project.

From the app menu, choose Project settings {@icon-project-settings@}.

Under Development, choose API keys.

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~}.

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 {@icon-codename@} 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.

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.

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.

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.

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: