|
|
Document methods |
|
|
|
|
|
Document methods |
|
|
|
|
|
|
Document methods |
|
|
|
|
|
Document methods |
|
|
|
|
|
|
||
In this topic, you can find examples of REST methods that can be used to retrieve or manipulate document data from a Kentico CMS instance using the REST service.
Document retrieval methods
Below, you can find examples of URLs under which object GET requests can be performed to retrieve document 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.
•Returns a single document of the given culture on the specified site:
•~/rest/content/site/<sitename>/<culture>/document/<aliaspath>, e.g. ~/rest/content/site/corporatesite/en-us/document/company/careers
•~/rest/content/currentsite/<culture>/document/<aliaspath>, e.g. ~/rest/content/currentsite/en-us/document/company/careers
•Returns all documents which start with the specified alias path:
•~/rest/content/site/<sitename>/<culture>/all/<aliaspath>, e.g. ~/rest/content/site/corporatesite/en-us/all/news
•~/rest/content/currentsite/<culture>/all/<aliaspath>, e.g. ~/rest/content/currentsite/en-us/all/news
•Returns all child documents of the given document:
•~/rest/content/site/<sitename>/<culture>/childrenof/<aliaspath>, e.g. ~/rest/content/site/corporatesite/en-us/childrenof/news
•~/rest/content/currentsite/<culture>/childrenof/<aliaspath>, e.g. ~/rest/content/currentsite/en-us/childrenof/news
|
Constants for default culture and all cultures
If you want to get documents in the default culture, there is a special constant defaultculture, which you can use instead of the culture string. The same applies for all cultures, while the constant is allcultures in this case.
|
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/content/site/corporatesite/en-us/document/home HTTP/1.1 User-Agent: Fiddler Authorization: Basic <enter Base64-encoded <username>:<password> here> Accept-Charset: utf-8 Host: localhost Content-Type: text\xml |
Besides the GET requests listed above, the REST service also supports the PUT, DELETE and POST Http methods. You can update, delete and insert documents (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 documents:
•Creates new document in the given culture, website and alias path location:
•~/rest/content/site/<sitename>/<culture>/document/<aliaspath>, e.g. ~/rest/content/site/corporatesite/en-us/document/news
•~/rest/content/currentsite/<culture>/document/<aliaspath>, e.g. ~/rest/content/currentsite/en-us/document/news
•Updates the specified document:
•~/rest/content/site/<sitename>/<culture>/document/<aliaspath>, e.g. ~/rest/content/site/corporatesite/en-us/document/news
•~/rest/content/currentsite/<culture>/document/<aliaspath>, e.g. ~/rest/content/currentsite/en-us/document/news
•Publishes the specified document:
•~/rest/content/site/<sitename>/<culture>/publish/<aliaspath>, e.g. ~/rest/content/site/corporatesite/en-us/publish/news/mynewsitem
•~/rest/content/currentsite/<culture>/publish/<aliaspath>, e.g. ~/rest/content/currentsite/en-us/publish/news/mynewsitem
•Performs check-out of the specified document:
•~/rest/content/site/<sitename>/<culture>/checkout/<aliaspath>, e.g. ~/rest/content/site/corporatesite/en-us/checkout/news/mynewsitem
•~/rest/content/currentsite/<culture>/checkout/<aliaspath>, e.g. ~/rest/content/currentsite/en-us/checkout/news/mynewsitem
•Performs check-in of the specified document:
•~/rest/content/site/<sitename>/<culture>/checkin/<aliaspath>, e.g. ~/rest/content/site/corporatesite/en-us/checkin/news/mynewsitem
•~/rest/content/currentsite/<culture>/checkin/<aliaspath>, e.g. ~/rest/content/currentsite/en-us/checkin/news/mynewsitem
•Archives the specified document:
•~/rest/content/site/<sitename>/<culture>/archive/<aliaspath>, e.g. ~/rest/content/site/corporatesite/en-us/archive/news/mynewsitem
•~/rest/content/currentsite/<culture>/archive/<aliaspath>, e.g. ~/rest/content/currentsite/en-us/archive/news/mynewsitem
•Moves the specified document to the next workflow step:
•~/rest/content/site/<sitename>/<culture>/movetonextstep/<aliaspath>, e.g. ~/rest/content/site/corporatesite/en-us/movetonextstep/news/mynewsitem
•~/rest/content/currentsite/<culture>/movetonextstep/<aliaspath>, e.g. ~/rest/content/currentsite/en-us/movetonextstep/news/mynewsitem
•Moves the specified document to the previous workflow step:
•~/rest/content/site/<sitename>/<culture>/movetopreviousstep/<aliaspath>, e.g. ~/rest/content/site/corporatesite/en-us/movetopreviousstep/news/mynewsitem
•~/rest/content/currentsite/<culture>/movetopreviousstep/<aliaspath>, e.g. ~/rest/content/currentsite/en-us/movetopreviousstep/news/mynewsitem
•Deletes the specified document:
•~/rest/content/site/<sitename>/<culture>/document/<aliaspath>, e.g. ~/rest/content/site/corporatesite/en-us/document/news
•~/rest/content/currentsite/<culture>/document/<aliaspath>, e.g. ~/rest/content/currentsite/en-us/document/news
|
Please note
If you specify a NodeID and a DocumentID is not specified, the operation is considered as new culture version creation. If you want to create a linked document, you have to specify a NodeLinkedNodeID in the request.
|
|
Validation of inserted or updated data
Please note that when inserting or updating document 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.
|
Below, you can find examples of document manipulation requests. For testing purposes, you can use Fiddler to send the requests to your web application and see the results.
The following example creates a sample document in the content tree.
POST http://localhost/CMS/rest/content/site/CorporateSite/en-us/document/Home HTTP/1.1 User-Agent: Fiddler Authorization: Basic <enter Base64-encoded <username>:<password> here> Host: localhost Content-Type: text\xml Content-Length:165
<CMS_MenuItem> <NodeClassID><enter class ID here></NodeClassID> <DocumentName>Services</DocumentName> <DocumentPageTemplateID><enter template ID here></DocumentPageTemplateID> </CMS_MenuItem> |
The following example updates the sample document created by the example above.
PUT http://localhost/CMS/rest/content/site/CorporateSite/en-us/document/Home/Services HTTP/1.1 User-Agent: Fiddler Authorization: Basic <enter Base64-encoded <username>:<password> here> Host: localhost Content-Type: text\xml Content-Length:81
<CMS_MenuItem> <DocumentName>Services MODIFIED</DocumentName> </CMS_MenuItem> |
The following example creates a new language version of the document created by the first example in this section.
POST http://localhost/CMS/rest/content/site/CorporateSite/cs-cz/document/Home/Services HTTP/1.1 User-Agent: Fiddler Authorization: Basic <enter Base64-encoded <username>:<password> here> Host: localhost Content-Type: text\xml Content-Length:103
<CMS_MenuItem> <NodeID>51939</NodeID> <DocumentName>Services CZ</DocumentName> </CMS_MenuItem> |
In case that you need to specify an empty value in a document 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 Home page of the sample Corporate Site and ensures that it will not have any user specified in the Document created by field.
PUT http://localhost/CMS/rest/content/currentsite/en-us/document/home HTTP/1.1 User-Agent: Fiddler Authorization: Basic <enter Base64-encoded <username>:<password> here> Host: localhost Content-Type: text\xml Content-Length: 271
<CMS_File><DocumentCreatedByUserID>##null##</DocumentCreatedByUserID></CMS_File> |
