Getting data using REST

The REST service allows you to retrieve page and object data from Kentico instances.

Send requests using the GET HTTP method to a URL in format: <REST base URL>/<resource path>

The base URL of the Kentico REST service is <site domain name>/rest. For example, if your site is running at http://localhost/Kentico, use http://localhost/Kentico/rest as the base URL of the service. To learn about the available resource paths for pages and objects, see the tables in the sections below. The requests return data in either XML, JSON, RSS or Atom format (see Examples of data retrieved via the REST service for more information).

REST base URL

Sending a GET request to the base URL of the REST service exposes the service document (for ODATA browsing). The document contains a list of all available primary object types (without child and binding object types) and the URLs under which the objects can be accessed. See also: ODATA service documents

Character encoding

Data retrieval requests return the results in the server's default character encoding. To get the results in a different encoding type, set the encoding in the Accept-Charset field of the GET request's HTTP header. If the specified encoding is not available, the system uses the Default encoding configured in Settings -> Integration -> Rest.

Example
GET http://localhost/Kentico/rest/cms.user/administrator HTTP/1.1
Authorization: Basic UmVzdENsaWVudDpNeVBhc3N3b3Jk
Accept-Charset: utf-8
Content-Type: text\xml

Getting page data

To load the data of pages from Kentico websites, send GET requests to the appropriate URL – append the resource paths described below to the base URL of your REST service.

You can further configure the data retrieval by adding query string parameters to the URL.

Resource format and example Description
Single page

/content/currentsite/<culture>/document/<alias path>
/content/currentsite/en-us/document/company/careers
______________________________________________________

A single page in the given culture from the site running on the domain in the base URL.

Identify the page using its alias path.

/content/site/<site name>/<culture>/document/<alias path>
/content/site/corporatesite/en-us/document/company/careers
_

A single page in the given culture on the specified site.
Multiple pages

/content/currentsite/<culture>/all/<alias path>
/content/currentsite/en-us/all/news


/content/site/<sitename>/<culture>/all/<alias path>
/content/site/corporatesite/en-us/all/news
_

All pages starting with the specified alias path.

/content/currentsite/<culture>/childrenof/<alias path>
/content/currentsite/en-us/childrenof/news


/content/site/<site name>/<culture>/childrenof/<alias path>
/content/site/corporatesite/en-us/childrenof/news
_

All child pages under the specified parent page. Does not include the parent page itself.

Culture constants

You can use the following constants instead of culture codes in page REST calls:

  • defaultculture - the page version in the site's default culture
  • allcultures - page versions in all available cultures

Example: /content/currentsite/defaultculture/document/company/careers

Getting object data

To load the data of objects from Kentico, send GET requests to the appropriate URL – append the resource paths described below to the base URL of your REST service.

Most object resources start with an object type value. To find the value for specific object types, open the System application in the Kentico administration interface and select the Object types tab.

You can further configure the data retrieval by adding query string parameters to the URL.

Resource format and example Description
Multiple objects

/<object type>
/cms.country
_

All objects of the given type assigned to the site running on the domain in the base URL.

If the object type does not use site bindings, returns all objects of the given type.

/<object type>/site/<site name>
/cms.country/site/corporatesite
_

All objects of the given type assigned to the specified site.

If the object type does not use site bindings, returns all objects of the given type.

/<object type>/global
/cms.emailtemplate/global

_

All global objects of the given type (objects not assigned to any site).

If the object type does not use site bindings, returns all objects of the given type.

/<object type>/all
/cms.emailtemplate/all
_________________________________________________________

All objects of the given type (site-related objects from all sites and global objects).

Note:

  • /all object retrieval requests only work if the user account used for authentication has the Global administrator privilege level.
  • The REST service does not allow /all object retrieval for requests that use the hash URL parameter for authentication

These are intentional security limitations that protect global data.

Single object

/<object type>/<id>
/cms.country/271
_

Object of the given type with the specified identifier (primary key ID).

Ignores site bindings – object IDs are unique across all sites in the system.

/<object type>/<code name>
/cms.country/usa
_

Object of the given type with the specified code name.

For object types with site bindings, always returns the object assigned to the site running on the domain in the base URL.

/<object type>/site/<site name>/<object code name or guid>
/cms.emailtemplate/site/corporatesite/Blog.NotificationToModerators
/cms.emailtemplate/site/corporatesite/e431b7e6-9e6c-409d-a1d9-748cbf51b5d6 

Object of the given type with the specified code name or GUID value, assigned to the specified site.
/<object type>/global/<object code name or guid>
/cms.emailtemplate/global/Blog.NotificationToModerators
/cms.emailtemplate/global/607ed253-7842-48be-98d7-63e0714a6ad1
___________________________________________________________________
Global object of the given type with the specified code name or GUID value.
Child objects
/<object type>/<id>/children
/cms.country/271/children
_
All object types that are supported as child types for the specified object. Only ID values can be used to identify the parent object.
/<object type>/<id>/children/<child object type>
/cms.country/271/children/cms.state
_
All objects of the given type that are children of the specified parent object. Only ID values can be used to identify the parent object.
Binding objects
/<object type>/<id>/bindings
/cms.user/53/bindings
_
All object types that are used as binding types (represent relationships with other objects) for the specified object. Only ID values can be used to identify the object.
/<object type>/<id>/bindings/<binding object type>
/cms.user/53/bindings/cms.usersite
_

All objects of the given binding type that exist for the specified object. Only ID values can be used to identify the object.

Custom tables

/cms.customtable/<custom table code name>
/cms.customtable/customtable.sampletable
_

The class definition of the specified custom table (includes data such as the custom table's names, field definitions and search settings).

/customtableitem.<custom table code name>
/customtableitem.customtable.sampletable
_

The data records stored in the specified custom table.
Forms
/cms.form/<form code name>
/cms.form/contactus
_
The class definition of the specified form (includes data such as the form's names, basic settings and field definitions).

/bizformitem.bizform.<form code name>
/bizformitem.bizform.contactus
_

The data records stored for the specified form.
Other
/<object type>/site
/cms.country/site
_

Lists all sites on which the specified object type is available and provides the REST URLs under which the object data can be retrieved for individual sites (for ODATA browsing).

/macro/<expression>
/macro/CurrentSite.SiteName

Evaluates the given macro expression and serializes the result. Only works for macros that return a serializable result.

When creating the macro expression:

  • Do NOT add the encapsulating bracket characters
  • Use URL encoding for forbidden URL characters

Data loading parameters

When loading data via REST, you can append the following query string parameters to the request URL:

Parameter Value (default bold) Description
General
format xml/json/atom10/rss20

Sets the format of the retrieved data. For example, append ?format=json to the request URL to get data in JSON format.

See also: Examples of data retrieved via the REST service

localize
______________________
culture code
__________________________

If added, the system resolves all localization expressions inside the returned data. Without this parameter, requests always return localization expressions in unresolved format. Supported by both page and object retrieval requests.

Specify the target language by entering the corresponding culture code into the parameter's value. You can find the available culture codes in the Localization application on the Cultures tab.

For example, append ?localize=fr-fr to the request URL to resolve all localization expressions into their French value (or the value in the default UI culture if the expression is not defined in French).

hash hash string

Allows you to authenticate the request without requiring an authentication header.

See Authenticating REST requests to learn how to generate the hash value.

Pages
classnames page type code name (all)

Limits which page types the request returns. Specified as a list of page type code names separated by semicolons.

For example, to retrieve only cms.article pages, append ?classnames=cms.article to the request URL.

coupleddata true/false

Determines if the request retrieves data stored in the fields of specific page types (coupled data).

The default behavior depends on the type of the page request:

  • Requests for single pages contain coupled data by default
  • Requests for multiple pages that do not specify the page type (classnames parameter) do NOT load coupled data by default

For example, to load pages with coupled data, append ?coupleddata=true to the request URL.

combinewithdefaultculture true/false

Indicates if the request loads the default language versions of pages if they do not exist in the specified culture.

To load the default language versions of pages, append ?combinewithdefaultculture=true to the request URL.

selectonlypublished

true/false

Determines if the request loads only pages that are published on the live site.

To also retrieve unpublished pages , append ?selectonlypublished=false to the request URL.

version published/last

Determines if the request returns the page versions that are published on the live site or the latest version that is being edited in the Pages application (when using Workflow).

To load the latest page versions, append ?version=last to the request URL.

Multiple pages or objects
where SQL code (empty)

SQL WHERE condition for filtering the loaded data. The parameter only allows the following types of SQL syntax:

  • column names, values and basic operators: =, !=, >, <
  • AND & OR operators, parentheses
  • column BETWEEN value AND value
  • column LIKE value
  • column IN (values)
  • column IS NULL
  • NOT keyword for the above expressions (NOT BETWEEN, NOT LIKE, NOT IN, IS NOT NULL)

Other expressions and SQL functions are not supported.

Example: ~/rest/cms.user?Where=UserPrivilegeLevel=1

Note: To avoid ambiguity, ensure that where parameter values are URL encoded. For example, occurrences of the % character in LIKE expressions should be replaced by the encoded equivalent – %25.

orderby SQL code (empty)

SQL ORDER BY clause for modifying the order of the items in the data. The parameter allows only the following values:

  • one or more column names (separated by commas)
  • the ASC and DESC keywords

Other SQL expressions and functions are not supported.

Append ?orderby=##default## to use alphabetical order based on the object display name.

columns column names (all columns)

Limits which data columns of the object or page are loaded. The parameter allows only the following values:

  • one or more column names (separated by commas)
  • SQL aliases for columns defined using the AS keyword (must be upper case)

For example, to load only the UserName and UserID columns when retrieving users, append ?columns=UserName,UserID to the request URL.

If you add the columns parameter, the binary parameter is ignored (you can choose whether to include binary columns by enumerating the corresponding columns).

topn integer (all records)

SQL TOP N clause for filtering the loaded data.

For example, to load only the first 10 records, append ?topn=10 to the request URL.

Multiple objects
offset integer (first record)

Sets the number of the first record that the request returns (according to the order of the data). Allows you to implement paging of the data.

For example, to load data starting from the third item in the dataset, append ?offset=2 to the request URL.

Note: The offset parameter only works when getting object data (not supported for pages).

maxrecords integer (all records)

Limits the maximum number of retrieved records. You can use the maxrecords parameter in combination with the offset parameter to retrieve a specific range of records.

For example, to load items 11–20 from the data, append ?offset=10&maxrecords=10 to the request URL.

Note: The maxrecords parameter only works when getting object data (not supported for pages).

Objects
objectdata true/false

Indicates whether the request retrieves the data fields of objects.

To load only the metadata of an object, append ?objectdata=false&metadata=true to the request URL.

metadata true/false

Determines if the request retrieves the metadata of objects (type, list of properties / columns).

To load the metadata, append ?metadata=true to the request URL.

binary true/false

Indicates whether the request retrieves binary data (e.g. the data of files uploaded into form fields). Binary data is retrieved in Base64 format.

To include the binary data in the response, append ?binary=true to the request URL.

children true/false

Indicates whether the result includes child objects.

To load child objects, append ?children=true to the request URL.

maxrelativelevel integer (all levels)

If the children parameter is true, this parameters sets the maximum depth of the exported object tree structure.

For example, to load all child objects down to the second level of the object tree, append ?children=true&maxrelativelevel=2 to the request URL.

bindings true/false

Determines if the retrieved data includes bindings to child objects and sites. Requests only return bindings if the objectdata parameter is true.

To load object data with its bindings, append ?bindings=true to the request URL.

otherbindings true/false

Determines if the retrieved data includes bindings to other objects (M:N relationships). Requests only return bindings if the objectdata parameter is true.

To load object data with bindings to other objects, append ?otherbindings=true to the request URL.

metafiles true/false

Determines if the retrieved data includes metafiles attached to the object

To load metafiles, append ?metafiles=true to the request URL.

relationships true/false

Determines if the retrieved data includes object relationships.

To load relationships, append ?relationships=true to the request URL.

categories true/false

Determines if the retrieved data includes the object's category structure (if the object is stored in a hierarchical category structure).

To load the category structure, append ?categories=true to the request URL.

translations true/false

Indicates whether the result includes a translation table of foreign keys.

To load the translation table, append ?translations=true to the request URL.

hierarchy true/false

If true, the response data is exported in a hierarchical structure (if false, the children – bindings – parent structure is flat).

To export the data in a hierarchical structure, append ?hierarchy=true to the request URL.


Was this page helpful?