Is this really the version you are looking for? Kentico Xperience 8 Documentation is no longer updated. Use the switcher in the header to choose your product version.
The REST service allows you to retrieve document and object data from Kentico instances.
Send requests using the GET HTTP method (opens in a new tab) 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 documents 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 object types and the URLs under which the objects can be accessed. See also: ODATA service documents
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.
GET http://localhost/Kentico/rest/cms.user/administrator HTTP/1.1
Authorization: Basic UmVzdENsaWVudDpNeVBhc3N3b3Jk
Accept-Charset: utf-8
Content-Type: text\xmlTo load the data of documents 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 document | |
/content/currentsite/<culture>/document/<alias path> | A single document in the given culture from the site running on the domain in the base URL. Identify the document using its alias path. |
/content/site/<site name>/<culture>/document/<alias path> | A single document in the given culture on the specified site. |
Multiple documents | |
/content/currentsite/<culture>/all/<alias path> /content/currentsite/en-us/all/news /content/site/<sitename>/<culture>/all/<alias path> | All documents starting with the specified alias path. |
/content/currentsite/<culture>/childrenof/<alias path> /content/site/<site name>/<culture>/childrenof/<alias path> | All child documents under the specified parent document. Does not include the parent document itself. |
Culture constants
You can use the following constants instead of culture codes in document REST calls:
Example: /content/currentsite/defaultculture/document/company/careers
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> | 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 | All objects of the given type (site-related objects from all sites and global objects). Note: The REST service does not allow /all object retrieval for requests that use the hash URL parameter for authentication. This is an intentional security limitation that protects global data. |
Single object | |
/<object type>/<id or guid> /cms.country/271 | Object of the given type with the specified identifier (ID or GUID value). Ignores site bindings — object IDs and GUIDs are unique across all sites in the system. |
/<object type>/<code name> | 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> /cms.emailtemplate/site/corporatesite/Blog.NotificationToModerators | Object of the given type with the specified code name, assigned to the specified site. |
/<object type>/global/<object code name> /cms.emailtemplate/global/Blog.NotificationToModerators | Global object of the given type with the specified code name. |
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> | The data records stored for the specified form. |
Other | |
/<object type>/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:
|
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. |
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 document 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. |
Documents | ||
classnames | document type code name (all) | Limits which document types the request returns. Specified as a list of document type code names separated by semicolons. For example, to retrieve only cms.article documents, append ?classnames=cms.article to the request URL. |
coupleddata | true/false | Determines if the request retrieves data stored in the fields of specific document types (coupled data). To load documents without coupled data, append ?coupleddata=false to the request URL. |
combinewithdefaultculture | true/false | Indicates if the request loads the default language versions of documents if they do not exist in the specified culture. To load the default language versions of documents, append ?combinewithdefaultculture=true to the request URL. |
selectonlypublished | true/false | Determines if the request loads only documents that are published on the live site. To also retrieve unpublished documents , append ?selectonlypublished=false to the request URL. |
version | published/last | Determines if the request returns the document 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 document versions, append ?version=last to the request URL. |
Multiple documents or objects | ||
where | SQL code (empty) | SQL WHERE condition for filtering the loaded data. The parameter only supports basic SQL syntax – certain SQL keywords may not work correctly. 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 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 only supports basic SQL syntax — certain SQL keywords may not work correctly. 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 document are loaded. 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 documents). |
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 documents). |
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. |