Manipulating data using REST

The REST service allows you to manipulate the data of pages and objects on Kentico instances.

Send requests using the POST, PUT or DELETE HTTP method to the appropriate URL. See the following documentation pages for details:

• Managing pages using REST
• Managing objects using REST

General data manipulation parameters

When managing pages or objects via REST, you can append the following query string parameters to the request URL:

Setting fields to empty values

If you need to set a page or object field to an empty value using a REST request, use the following expression instead of an actual value:

• ##null## (for data in XML format)
• null (for data in JSON format)

The null expression is particularly useful for non-string fields (typically fields storing foreign key IDs), where an empty string value would not produce the desired results.

For example, the following request updates the Home page of the sample Corporate Site and ensures that it does not have a user specified in the Created by field:

• HTTP method: PUT

• URL: ~/rest/content/site/corporatesite/en-us/document/Home

• Data (XML format):

  Copy

  
  
  
    <CMS_MenuItem>
       <DocumentCreatedByUserID>##null##</DocumentCreatedByUserID>
    </CMS_MenuItem>
  
  
    

Uploading attachment files

When uploading files via the REST service, use the following format for the binary data:

• base 64 encoding in requests using the XML data format
• byte array values in requests using the JSON data format

Carefully consider the data type of the target field. Most page and object fields in Kentico do not store binary data directly, but instead contain the GUID of the corresponding attachment object. To find information about the requirements for your scenario, send a GET request for an existing object of the given type and check the resulting data.

For example, use the following steps to create a new CMS.File page, including an image file as an attachment:

1. Send a request to create the attachment file itself (cms.attachment object type, base64 encoding for the file binary in the AttachmentBinary field):

   • HTTP method: POST

   • URL: ~/rest/cms.attachment/currentsite

   • Data (XML format):

     Copy

     
     
     
       <CMS_Attachment>
         <AttachmentName>NewAttachmentFile.png</AttachmentName>
         <AttachmentExtension>.png</AttachmentExtension>
         <AttachmentSize>3180</AttachmentSize>
         <AttachmentMimeType>image/x-png</AttachmentMimeType>
         <AttachmentImageWidth>183</AttachmentImageWidth>
         <AttachmentImageHeight>47</AttachmentImageHeight>
         <AttachmentBinary></AttachmentBinary> <!-- Insert base 64 encoded binary data -->
       </CMS_Attachment>
     
     
       

2. Store the AttachmentGuid value from the data of the response to the POST request that created the attachment.

3. Create the CMS.File page (set the FileAttachment field to the GUID of the new attachment object):

   • HTTP method: POST

   • URL: ~/rest/content/currentsite/en-us/document/Images

   • Data (XML format):

     Copy

     
     
     
       <CMS_File>
         <NodeClassID>1685</NodeClassID>
         <DocumentExtensions>.png</DocumentExtensions>
         <DocumentType>.png</DocumentType>
         <FileName>NewAttachmentFile</FileName>
         <FileAttachment>96d6dfc9-4f3a-4a30-95af-4d7cc5a36f9a</FileAttachment> <!-- Insert the GUID of the appropriate attachment object -->
       </CMS_File>
     
     
       

4. Store the DocumentID value from the data of the response to the POST request that created the new CMS.File page.

5. Update the data of the attachment object to include the ID of the new page (set the AttachmentDocumentID field to the DocumentID of the page):

   • HTTP method: PUT

   • URL: ~/rest/cms.attachment/<attachment GUID>

   • Data (XML format):

     Copy

     
     
     
       <CMS_Attachment>
         <AttachmentDocumentID>120</AttachmentDocumentID> <!-- Insert the DocumentID of the page to which the file is attached -->
       </CMS_Attachment>