This section provides information about the way the Legacy REST Web Services server expects to receive parameter values.
Using Primitive Values in Input
Format primitive values as shown in the following table.
Value Type | Values Accepted |
|---|---|
| A sequence of characters. For example, “MyUsername.” |
| An integer or decimal number. For example, “123” or “123.456.” |
|
|
Using Multiple Values in Input
The Legacy REST Web Services server will accept map and collection input when you set the values of properties that accept multiple values.
You can configure the way the Legacy REST Web Services server appends or replaces multiple values in a repository item property.
When you set the value of a non-repository, Nucleus component property, the Legacy REST Web Services server will replace all values with any new values that you set. To append a value to an existing collection, you must supply all the existing values along with the new values. Note that unless you are setting the value of a repository item, you must specify the Java classes used for the container and the contents.
The following example shows a Legacy REST Web Services request that appends a value to a non-repository component property. It includes all existing values in the property along with the new value. To remove a value, make a similar request that includes only the values that you wish to remain in the property.
curl -v -b cookies.txt -X POST \
-H "Content-Type: application/json" \
-d "{'atg-rest-param-class-types':{'container-class':'java.util.ArrayList',
'element-class':'java.lang.String'},
'arg1':['Existing String in the Collection','New String for the Collection']}" \
http://myserver:7003/rest/bean/atg/MyDog/tricks?atg-rest-json-input=trueSpecifying Java Classes for Multiple Value Input
Specify the Java classes for your array, collection, and map values as shown in the following table.
Value Type | Format |
|---|---|
|
For example:
|
|
For example:
|
|
For example:
|
If your input is in JSON format, you can use the atg-rest-param-class-types control parameter to specify Java classes. The atg-rest-param-class-types parameter includes two components, container-class and element-class. Include this attribute in your JSON input as shown below.
{'atg-rest-param-class-types':{'container-class':
'java.util.ArrayList','element-class':
'java.lang.String'},'arg1':['sit','stay','speak']}See information about the atg-rest-param-class-types parameter in the Adding Control Parameters section.
Legacy REST Web Services are configured to append values to repository item properties using the atg-rest-append-multi-values control parameter. For information this parameter, refer to the Using Multiple Values in Input section.
Appending Values to Repository Item Properties
To append data to a repository item property that holds multiple values, set the new value as you would for a single value property.
The following example adds two repository item reference values to a repository item property that can hold multiple values. Any existing values in that property will remain there.
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>/atg/commerce/gifts/Giftlists/gift-list/gl40050, /atg/commerce/gifts/Giftlists/gift-list/gl40052</arg1></parameters>" \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/ user/130001/giftlists
Note: The Legacy REST Web Services server is configured to append values to repository item properties that accept multiple values by default. The appendMultiValuesByDefault configuration property controls this behavior for repository item properties. If you have reconfigured this setting, set the atg-rest-append-multi-values control parameter to true for each Legacy REST Web Services request that should append the new value.
Replacing Multiple Values in a Repository Item Property
To replace all the existing values in a repository item property that holds multiple values, include the atg-rest-append-multi-values control parameter with your Legacy REST Web Services request. Set the value of the control parameter to false.
Note: You can only use the rest-append-multi-values control parameter with repository item properties. It does not affect the way you can update non-repository properties.
The following example replaces all the values that are currently in a repository item property that holds multiple values. Only the repository item reference that is in the functional parameter will remain in the property.
curl -v -b cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>/atg/commerce/gifts/Giftlists/gift-list/gl40049</arg1> </parameters>" \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/ user/130001/giftlists?atg-rest-append-multi-values=false
JSON Markup Input for Multiple Value Repository Item Properties
If you are setting multiple values in a repository item property, you can use standard JSON markup for the collection or map value. Include the atg-rest-json-input with your Legacy REST Web Service request and set its value to true.
You can include JSON markup for multiple values in any input format. The following example shows a Legacy REST Web Services request that includes a JSON collection in an XML message body parameter.
curl.exe -v -b cookies.txt -X POST \ -H "Content-Type: application/xml" \ -d "<parameters><arg1>[ "/atg/commerce/gifts/Giftlists/gift-list/gl40050", "/atg/commerce/gifts/Giftlists/gift-list/gl40052" ]</arg1></parameters>" \ http://myserver:8080/rest/repository/atg/userprofiling/ProfileAdapterRepository/ user/130001/giftlists?atg-rest-json-input=true
Using Object Values in Input
To set a property that takes a Java object as its value, include the atg-rest-class-type control parameter along with the initial properties for the object in the positional parameter for the property value. The atg-rest-class-type control parameter specifies the Java class of the object. Use either JSON or XML to enclose the positional parameter.
The Legacy REST Web Services server will return a Boolean value to indicate whether the object property has been set successfully. If it is set successfully, the returned value is true.
Note: The Legacy REST Web Services interface can only create objects of classes that have a null constructor. At least one constructor for the class must have no arguments.
The following is an object property value encoded in JSON. The class for the object is atg.MyObjectValue. The following parameters set properties of the new object.
{"arg1":
{"atg-rest-class-type" : "atg.MyObjectValue",
{"atg-rest-values": {
"name" : "Berthoud",
"height" : "1"}
}Here is the same object property value, encoded in XML.
<parameters>
<arg1>
<atg-rest-class-type>atg.MyObjectValue</atg-rest-class-type>
<atg-rest-values>
<name>Berthoud</name>
<height>1</height>
</arg1>
</parameters>
The following example shows a POST request to set an object property value for a Nucleus component.
$ curl -v -b cookies.txt -X POST -H "Content-Type: application/json" -d
"{"arg1":{"atg-rest-class-type":"atg.MyObjectValue",
"name":"Berthoud","height":"1"}}"
http://myserver:7003/rest/bean/atg/MyDog/objectvalue
* About to connect() to myserver port 7003 (#0)
* Trying 12.34.567.890... connected
* Connected to myserver (12.34.567.890) port 7003 (#0)
> POST /rest/bean/atg/MyDog/objectvalue HTTP/1.1
> User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/
0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5
> Host: myserver:7003
> Accept: */*
> Cookie: JSESSIONID=
llf3PN8N0CfQ6h41Y278NfLjvCJZn6CR8ydhQRbg7GTQ7Nn5mW8p!1359398113;
DYN_USER_CONFIRM=838bac4608584930cf177410e3b46448; DYN_USER_ID=110001
> Content-Type: application/json
> Content-Length: 69
>
< HTTP/1.1 200 OK
< Date: Wed, 29 Feb 2012 05:52:39 GMT
< Transfer-Encoding: chunked
< Content-Type: application/json; charset=UTF-8
< X-ATG-Version: version=
QVRHUGxhdGZvcm0vMTAuMSxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjE=
< X-Powered-By: Servlet/2.5 JSP/2.1
<
* Connection #0 to host myserver left intact
* Closing connection #0
{"atgResponse": true}Using Nested Multiple Value Objects in Input
To set a property value that takes a Java object that holds other Java objects, use the atg-rest-class-descriptor control parameter to specify the Java class of the nested objects. For example, if you are setting a property value that takes a List of Sets, indicate the Java class of the Set using the atg-rest-class-descriptor parameter. Then include the values for the nested Sets.
The name of the parameter inside the atg-rest-class-descriptor matches the name of one of the actual values that you supply later in the input parameter.
The input structure for nested multiple value objects builds on the structure for input objects in general.
The following example uses the atg-rest-class-descriptor control parameter to specify that the value of the myListOfSets property is a java.util.ArrayList object. That ArrayList object holds java.util.HashSet objects. After the atg-rest-class-descriptor, the example provides the values that are nested inside the myListOfSets property.
{arg1 : {
"atg-rest-class-type":"foo.class.WithNestedMultis",
"atg-rest-class-descriptor": {
"myListOfSets": {
"container-class": "java.util.ArrayList",
"element-class": "java.util.HashSet"
}
},
"myListOfSets": [["red","blue"],["green","yellow"]]
}
}Here is the same object property value, encoded in XML.
<arg1> <atg-rest-class-type>foo.class.WithNestedMultis</atg-rest-class-type> <atg-rest-class-descriptor> <myListOfSets> <container-class>java.util.ArrayList</container-class> <element-class>java.util.HashSet</element-class> </myListOfSets> </atg-rest-class-descriptor> <myListOfSets> <element> <element>red</element> <element>blue</element> </element> <element> <element>green</element> <element>yellow</element> </element> </myListOfSets> </arg1>
Using Three or More Nested Levels
Include additional container-class and element-class parameters for each nested level of multiple value objects. The element-class parameter of the parent object holds the additional container-class and element-class parameters.
For example:
"atg-rest-class-descriptor": {
"myListOfSets": {
"container-class": "java.util.ArrayList",
"element-class": {
"container-class": "java.util.HashSet",
"element-class": "java.util.HashMap"
}
}
}Adding Date Format in Input
Use the following date format when sending dates to the Legacy REST Web Services interface.
MM/DD/YYYY HH:MM:SS Z
For example, 01/29/2015 14:45:11 PDT
Setting Properties to Null
Use the atg-rest-null parameter to set the value of a component or repository item property to null. Set the property and include this parameter as the new value.
The following example sets the value of a component property to null.
$ curl -v -b cookies.txt -X POST \
-H "Content-Type: application/json" \
-d "{"arg1":"atg-rest-null"}" \
http://myserver:7003/rest/bean/atg/MyDog/name
* About to connect() to myserver port 7003 (#0)
* Trying 12.34.567.890... connected
* Connected to myserver (12.34.567.890) port 7003 (#0)
> POST /rest/bean/atg/MyDog/name HTTP/1.1
> User-Agent: curl/7.20.1 (i686-pc-cygwin) libcurl/7.20.1 OpenSSL/0.9.8r zlib/1.2.5 libidn/1.18 libssh2/1.2.5
> Host: myserver:7003
> Accept: */*
> Cookie: JSESSIONID=S31vPTNFpLQQ7Bj6l16wh5KgDqqv18yXxwy1khgBpvqRkW5NfQRm!1359398113; DYN_USER_CONFIRM=838bac4608584930c
f177410e3b46448; DYN_USER_ID=110001
> Content-Type: application/json
> Content-Length: 20
>
< HTTP/1.1 200 OK
< Date: Thu, 01 Mar 2012 01:18:50 GMT
< Transfer-Encoding: chunked
< Content-Type: application/json; charset=UTF-8
< X-ATG-Version: version=QVRHUGxhdGZvcm0vMTAuMSxDb21tZXJjZVJlZmVyZW5jZVN0b3JlLzEwLjE=
< X-Powered-By: Servlet/2.5 JSP/2.1
<
* Connection #0 to host myserver left intact
* Closing connection #0
{"atgResponse": true}
