Kentico CMS 6.0 Developer's Guide

Object methods

Object methods

Previous topic Next topic Mail us feedback on this topic!  

Object methods

Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

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.

 

 

InfoBox_Note

 

Object ID, GUID and code name

 

In all of the examples below, object ID, object GUID and object code name are interchangeable, i.e. you can use any of them to specify the respective object.

 

When using code names of site-related objects, the object with the code name assigned to the current site is always returned, unless a site is explicitly specified in the URL.

 

 

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:

 

POST http://localhost/CMS/rest/cms.user/administrator HTTP/1.1

User-Agent: Fiddler

Authorization: Basic <enter Base64-encoded <username>:<password> here>

Accept-Charset: utf-8

Host: localhost

Content-Type: text\xml

 

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

 

 

InfoBox_Exclamation

 

Validation of inserted or updated data

 

Please note that when inserting or updating object data via the REST service, no validation is performed on the side of Kentico CMS. You therefore need to ensure appropriate validation on the side of your application to prevent unwanted behavior.

 

 

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.

 

POST http://localhost/CMS/rest/cms.country HTTP/1.1

User-Agent: Fiddler

Authorization: Basic <enter Base64-encoded <username>:<password> here>

Host: localhost

Content-Type: text\xml

Content-Length: 271

 

<data><cms_country><CountryDisplayName>Test Country REST</CountryDisplayName><CountryName>TestCountryREST</CountryName></cms_country><CMS_State><StateDisplayName>Test State 1</StateDisplayName><StateName>TestState1</StateName><StateCode>TST</StateCode></CMS_State></data>

 

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

 

PUT http://localhost/CMS/rest/cms.country/TestCountryREST HTTP/1.1

User-Agent: Fiddler

Authorization: Basic <enter Base64-encoded <username>:<password> here>

Host: localhost

Content-Type: text\xml

Content-Length: 102

 

<data><cms_country><CountryDisplayName>Test Country MODIFIED</CountryDisplayName></cms_country></data>

 

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

 

POST http://localhost/CMS/rest/cms.country?format=json HTTP/1.1

User-Agent: Fiddler

Authorization: Basic <enter Base64-encoded <username>:<password> here>

Host: localhost

Content-Type: application/json

Content-Length:161

 

{ "CountryDisplayName":"Test JSON","CountryName":"TestJSON","cms.state": [{"StateCode":"TST","StateName":"TestStateJSON","StateDisplayName":"Test State JSON"}] }

 

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

 

PUT http://localhost/CMS/rest/cms.country/TestJSON HTTP/1.1

User-Agent: Fiddler

Authorization: Basic <enter Base64-encoded <username>:<password> here>

Host: localhost

Content-Type: application/json

Content-Length:45

 

{ "CountryDisplayName":"Test JSON MODIFIED" }

 

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

DELETE http://localhost/CMS/rest/cms.country/TestCountryREST HTTP/1.1

User-Agent: Fiddler

Authorization: Basic <enter Base64-encoded <username>:<password> here>

Host: localhost

 

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.

 

PUT http://localhost/CMS/rest/cms.site HTTP/1.1

User-Agent: Fiddler

Authorization: Basic <enter Base64-encoded <username>:<password> here>

Host: localhost

Content-Type: text\xml

Content-Length: 271

 

<CMS_Site><SiteDefaultStylesheetID>##null##</SiteDefaultStylesheetID></CMS_Site>