API Usage

• See the herd Terminology page for details of various terms and their descriptions.
• Obtain a copy of the API XSD or the generated model jar to ensure compliance with API XML NEED LINKS TO GitHub/Sonatype
• All passed in and returned data can be specified as either XML (i.e. application/xml) or JSON (application/json). For data being passed into a REST API, the "Content-Type" header should be set with the desired data format. For the returned data, the "Accept" header should be set.
• When sending JSON, the outer object is assumed and should not be passed. For example, if the request body contains the following XML tags:

<uploadSingleCompletionRequest>
   <sourceBusinessObjectDataKey>
      ...

then the JSON object would look as follows:

{
   "sourceBusinessObjectDataKey": ...
      ...

• Similarly for lists and collections, the repeated item tags are assumed. For example: if the body contains the following XML tags:

<partitionValues>
    <partitionValue>2014-04-01</partitionValue>
    <partitionValue>2014-04-02</partitionValue>
    ....
</partitionValues>

then the JSON collection would look as follows:

"partitionValues": [ "2014-04-01", "2014-04-02", ... ]

• All API's are relative to the root URL for a specific environment (i.e. http://:/dm-app/rest).
• When specifying non-ASCII printable characters, it is recommended to XML escape those characters. For example, the Start Of Heading character should be specified as "".
• XML "1.0" and "1.1" are supported for incoming operations whereas all responses are XML 1.1 (as of Release 2014.6.0). To specify the XML version, pass in the version within the header as follows:

<?xml version="<version>" encoding="UTF-8" standalone="yes"?>

• Please refer to the W3C 1.0 and 1.1 Wiki pages for supported character sets and reserved characters. For example, the Start Of Heading character is only supported in XML 1.1.
• When responses are generated, all characters are returned as is with the exception of the following characters which are XML escaped:

Character	Output
&	&
<	&lt;
>	&gt;
"	&quot; (attributes only)
'	&apos; (attributes only)
XML 1.1 Reserved Characters	&#x<value>

Error Handling

All REST API's will return with an appropriate HTTP status code. The following are some of the typical responses:

Status Code	Status Description	Error Description
200	Success	No errors found. The expected result is documented for each service endpoint above.
400	Bad Request	This is returned when any of the submitted parameters are invalid or if the structure of the XML or JSON doesn't match what's expected. For example, a required storage name wasn't specified when attempting to create a new storage.
404	Not Found	This is returned when a specified Id or key to an object isn't found.
405	Method Not Allowed	This is returned if an invalid operation is attempted on a REST endpoint. For example, a URI only handles GET, but POST was specified.
406	Not Acceptable	This is returned when none of the formats in the "accepts" header are supported.
409	Conflict	This is returned when an attempt is made to create an object that already exists.
415	Unsupported Media Type	This is returned when a content type is specified that is not consumable by the server.
500	Internal Server Error	This is returned when the server hits an invalid state or throws an exception. This should not be expected and represents a problem that should be reported.

When an error is generated, error information is returned. The following is an example:

<errorInformation>
    <statusCode>400</statusCode>
    <statusDescription>Bad Request</statusDescription>
    <message>Storage with name "S3_MANAGED" already exists.</message>
    <messageDetails>
         <message>cause exception message</message>
    </messageDetails>
</errorInformation>