This topic contains a list of querystring parameters supported by the REST service. You can append these parameters to the request URLs in order to further specify the behavior of the methods. The information in the parentheses explains the expected data type of the parameter along with its default value (in bold font).

 

General parameters

 

•Format (json/atom10/rss20/xml)

Sets the format of the request data. If specified for PUT/POST requests, this parameter has higher priority than the Content-Type parameter in the request header. For example, append ?format=json to the request URL to use the JSON format.

 

•Localize (string) [Only available after applying hotfix 7.0.4 or newer]
If added to a data retrieval request, the system resolves all localization expressions inside the returned data. Specify the target language by entering the corresponding culture code into the parameter's value. Without this parameter, requests always return localization expressions in unresolved format. The Localize parameter is supported by both object and document retrieval requests.
 
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 (string)
Allows you to authenticate the request without requiring an authentication header or Forms authentication. To generate a valid hash for a request:
 

a.Go to Site Manager -> Settings -> Integration -> REST.

b.Click Generate authentication hash.

c.Enter the full absolute URL of the REST request, including the protocol, website domain name, virtual directory, REST path, and query string parameters.

d.Click Authenticate.

 

The system adds the authentication hash parameter to the URL. You can copy the URL and use it to perform the REST request without any other type of authentication.

 

Object retrieval parameters

 

You can add the following parameters to object retrieval requests:

 

•ObjectData (true/false)

Indicates whether the request retrieves object data. 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 the object (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 to include child objects in the result. To load child objects, append ?children=true to the request URL.

 

•MaxRelativeLevel (int, -1 = 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 belongs to a category). To load the category structure, append ?categories=true to the request URL.

 

•Translations (true/false)

Indicates whether to include a translation table of foreign keys in the result. 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.

 

Multiple object retrieval parameters

 

When retrieving a dataset containing multiple objects, the following parameters allow you to filter the items and change their order:

 

•Where (string, empty by default)

SQL WHERE condition for filtering of the dataset. To filter retrieved data using a WHERE condition, append ?where=<text of the condition> to the request URL.
For example: ~/rest/cms.user?Where=UserIsEditor=1

 

•OrderBy (string, empty by default)

SQL ORDER BY clause for modifying the order of the items in the dataset. Append ?orderby=##default## to use alphabetical order based on the object display name.

 

•Columns (string, all columns by default)

Limits which data columns of the object are retrieved by the request. For example, to load only the UserName and UserID columns when retrieving users, append ?columns=UserName,UserID to the request URL. If you add this parameter, the Binary parameter is ignored (you can choose whether to include binary columns by enumerating the corresponding columns).

 

•TopN (int, all records by default)

SQL TOP N clause for filtering of the dataset. For example, to load only the first 10 retrieved records, append ?topn=10 to the request URL.

 

•Offset (int, first record by default)

Sets the number of the first record that the request returns (according to the order of the dataset). This parameter 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.

 

•MaxRecords (int, all record by default)

Limits the maximum number of retrieved records. You can use this parameter in combination with the Offset parameter to load pages containing a specific range of records. For example, to load items 11–20 from the dataset, append ?offset=10&maxrecords=10 to the request URL.

 

Document retrieval parameters

 

The following parameters are supported for requests that retrieve document data. You may also use the filtering and ordering parameters listed in the Multiple object retrieval parameters section.

 

•ClassNames (string, all classnames)

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.

 

•CombineWithDefaultCulture (true/false)

Indicates if the request should load the default language versions of documents if they do not exist in the specified culture. To load the language culture 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 CMS Desk (when using Workflow). To load the latest document versions, append ?version=last to the request URL.

 

•CoupledData (true/false)

Determines if the request retrieves the data stored in the fields of specific document types (coupled data). To load documents without coupled data, append ?coupleddata=false to the request URL.

 

Document deletion parameters

 

•DeleteAllCultures (true/false)

Indicates if the request also deletes all cultural versions of the specified document. To delete all culture versions of a document, append ?deleteallcultures=true to the request URL.

 

•DestroyHistory (true/false)

Indicates if the request also deletes the document's version history. To delete the version history together with the document, append ?destroyhistory=true to the request URL.

 

•DeleteProduct (true/false)

Indicates if the request also deletes the e-commerce product associated with the specified product document. To delete e-commerce products along with documents, append ?deleteproduct=true to the request URL.