In this topic, you can find examples of REST methods that can be used to retrieve or manipulate object data from a Kentico CMS instance using the REST service.

 

Object data retrieval methods

 

Below, you can find examples of URLs under which object GET requests can be performed to retrieve object data from a Kentico CMS instance. The URLs are listed as relative, so e.g. if your instance is running at http://localhost/KenticoCMS, you would perform a request listed as ~/rest in format http://localhost/KenticoCMS/rest. You can also achieve a more detailed specification of retrieved data by appending querystring parameters to the URLs. More information can be found in the URL parameters topic.

 

 

•Exposes the service document (for ODATA browisng). The document contains a list of all available object types and URLs under which objects of the type can be accessed:

•~/rest

 

•Returns all objects of the given object type (both site objects from all sites and global objects):

•~/rest/<objecttype>/all, e.g. ~/rest/cms.emailtemplate/all

 

•Returns all objects of the given object type assigned to the current site. If there is no site binding for the given object type, it returns all objects of the given type:

•~/rest/<objecttype>, e.g. ~/rest/cms.country

•~/rest/<objecttype>/currentsite, e.g. ~/rest/cms.country/currentsite

 

•Returns all objects of the given object type assigned to the specified site. If there is no site binding for the given object type, it returns all objects of the given type:

•~/rest/<objecttype>/site/<sitecodename>, e.g. ~/rest/cms.country/site/corporatesite
 

•Returns all global objects of the given object type (which are not assigned to any site). If there is no site binding for the given object type, it returns all objects of the given type:

•~/rest/<objecttype>/global, e.g. ~/rest/cms.emailtemplate/global

 

•Returns all sites on which the specified object type is available to the currently authenticated user and URLs under which the objects for the particular sites can be retrieved (for ODATA browsing):

•~/rest/<objecttype>/site, e.g. ~/rest/cms.country/site

 

•Returns an object of the given type with the specified ID, GUID or code name:

•~/rest/<objecttype>/<id>, e.g. ~/rest/cms.country/271

 

•Returns an object of the given type with the specified code name assigned to the current site:

•~/rest/<objecttype>/<objectcodename>, e.g. ~/rest/cms.country/usa

•~/rest/<objecttype>/currentsite/<objectcodename>, e.g. ~/rest/cms.country/currentsite/usa
 

•Returns a global object of the given type with the specified name:

•~/rest/<objecttype>/global/<objectcodename>, e.g. ~/rest/cms.emailtemplate/global/Blog.NotificationToModerators

 

•Returns all supported child object types for the given object (only object ID can be used in this URL, not code name or GUID):

•~/rest/<objecttype>/<id>/children, e.g. ~/rest/cms.country/271/children
 

•Returns all child objects of the specified object and of the given object type (only object ID can be used in this URL, not code name or GUID):

•~/rest/<objecttype>/<id>/children/<childrenobjecttype>, e.g. ~/rest/cms.country/271/children/cms.state
 

•Returns all binding object types supported by the given object (only object ID can be used in this URL, not code name or GUID):

•~/rest/<objecttype>/<id>/bindings, e.g. ~/rest/cms.user/53/bindings
 

•Returns all binding objects of the given type of the specified object (only object ID can be used in this URL, not code name or GUID):

•~/rest/<objecttype>/<id>/bindings/<bindingobjecttype>, e.g. ~/rest/cms.user/53/bindings/cms.usersite
 

•Returns TypeInfo of the given object type:

•~/rest/typeinfo/<objecttype>, e.g. ~/rest/typeinfo/cms.user
 

•Evaluates the given macro expression (without the encapsulating character sequence and with forbidden characters URL-encoded) and serializes the result:

•~/rest/macro/<expression>, e.g. ~/rest/macro/CurrentSite.SiteName

 

Custom table and Form data items vs. class definition

 

When working with custom tables or forms via the REST service, you need to use different URLs when you want to specify the table's or form's class definition and when you want to specify the data items stored in the custom table or form.

 

For class definition, you need to use:

 

•~/rest/cms.customtable/<customtablecodename>, e.g. ~/rest/cms.customtable/customtable.sampletable

•~/rest/cms.form/<formcodename>, e.g. ~/rest/cms.form/contactus

 

For the actual data items, you need to use:

 

•~/rest/customtableitem.<customtablecodename>, e.g. ~/rest/customtableitem.customtable.sampletable

•~/rest/bizformitem.bizform.<formcodename>, e.g. ~/rest/bizformitem.bizform.contactus

 

GET request result encoding

 

Data retrieval (GET) requests return the results encoded using the default server encoding. If you want to get the result in a different encoding, you need to specify the required encoding in the Accept-Charset field of the HTTP GET request. If the specified encoding is not available, UTF8 is used by default. Please note that this feature is only available in Kentico CMS 6.0 with applied hotfix 6.0.13 or later.

 

For example:

 

 

Object data manipulation methods

 

Besides the GET requests listed above, the REST service also supports PUT, DELETE and POST Http methods. You can update, delete and insert objects (respectively) using these Http methods. Both XML and JSON formats are supported when performing these requests.

 

The following URLs can be requested by the respective type of request in order to manipulate Kentico CMS objects:
 

HTTP POST method URLs

 

Creates a new object of the specified type.

•~/rest/<objectType>, e.g. ~/rest/cms.user

 

Creates a new object of the specified type and assigns it to the current website.

•~/rest/<objectType>/currentsite, e.g. ~/rest/cms.user/currentsite

 

Creates a new object of the specified type and assigns it to the specified website.

•~/rest/<objectType>/site/<sitename>, e.g. ~/rest/cms.user/site/corporatesite
 

HTTP PUT method

 

Updates the object of the specified type with the specified ID.

•~/rest/<objectType>/<id>, e.g. ~/rest/cms.user/53

 

Updates the object of the specified type with the specified code name and assigns it to the specified site.

•~/rest/<objectType>/site/<sitename>/<objectcodename>, e.g. ~/rest/cms.user/site/corporatesite/administrator

 

Updates the object of the specified type with the specified code name and assigns it to the current website.

•~/rest/<objectType>/<currentsite>/<objectcodename>, e.g. ~/rest/cms.user/currentsite/administrator

 

Updates the global object of the specified type with the specified code name.

•~/rest/<objectType>/global/<objectcodename>, e.g. ~/rest/cms.user/global/administrator

 

HTTP DELETE method

 

Deletes the object of the specified type with the specified ID.

•~/rest/<objectType>/<id>, e.g. ~/rest/cms.user/53

Deletes the object of the specified type with the specified code name assigned to the specified website.

•~/rest/<objectType>/site/<sitename>/<objectcodename>, e.g. ~/rest/cms.user/site/corporatesite/administrator

Deletes the object of the specified type with the specified code name assigned to the current website.

•~/rest/<objectType>/<currentsite>/<objectcodename>, e.g. ~/rest/cms.user/currentsite/administrator

Deletes the globlal object of the specified type with the specified code name.

•~/rest/<objectType>/global/<objectcodename>, e.g. ~/rest/cms.user/global/administrator

 

 

Examples of object manipulation requests

 

Below, you can find examples of object data manipulation requests. For testing purposes, you can use e.g. Fiddler to send the requests to your web application and see the results in the UI.

 

The following request creates a sample cms.country object based on the provided XML definition.

 

 

The following example updates the sample cms.country object created by the example above based on the provided XML data.

 

 

The following request creates a sample cms.country object based on the provided JSON definition.

 

 

The following example updates the sample cms.country object created by the example above based on the provided JSON data.

 

 

The following example deletes the sample cms.country object created by either of the examples above.
 

 

Null value macro

 

In case that you need to specify a null value in an object manipulation request, you can use the ##null## macro instead of an actual value. This is particularly useful for non-string fields (e.g. typically foreign keys) where an empty string value would not produce the desired results.

 

Please note that this feature is only available in Kentico CMS 6.0 with applied hotfix 6.0.14 or later.

 

The following example updates the sample Corporate Site and ensures that it will not have any default CSS stylesheet assigned.