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 name. To find the value for specific object types, view the Code name of classes in the Modules application, or the ClassName column of the CMS_Class database table.

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).
/typeinfo/<object type> /typeinfo/cms.user	The TypeInfo data for the specified object type. The TypeInfo is a set of properties that define the general behavior and basic properties of object types (classes) in Kentico.
/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 or Forms authentication. 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=UserIsEditor=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.