Processing envelope responses.
During processing response envelopes, programmers can use an XML parser and algorithms that handle changes in the number of elements that are returned in the envelope. This improves the reliability of scripts that process responses.
The contents of a response envelope change in length depending on when you call them (and between releases of the Watson Campaign Automation). For example, the GetJobStatus API returns responses of varying length depending on the status of the job (including WAITING, RUNNING, COMPLETE, and ERROR).
Unsuccessful responses or errors also adhere to the general format specified earlier. The XML elements in their bodies vary based on the type of error. The best way to become familiar with the responses that are caused by specific error conditions is to recreate them using the XML API Test Harness. If the Watson Campaign Automation is not available due to a maintenance outage, the following XML is returned:
<![CDATA[The system is currently down for maintenance.]]>
Forming XML API requests
The interfaces to the Watson Campaign Automation are facilitated through XML requests over Secure HTTP. You can make the request through either the POST or GET method.
Always begin the XML body format with the <Envelope> element followed by the <Body> element. For example:
<Body> <â€¦Contentâ€¦> </Body>
To pass parameters, list each parameter as a child element of the operation element, as shown.
Submitting an API request
Use API Endpoints to learn how to submit an API request.
To submit a Licensed API, user can refer to the Test Harness document, which is located in the XML API Test Harness file, to obtain the appropriate API endpoint.
XML is passed as the Body of a POST. To specify encoding (for example, UTF-8) of the XML you are submitting, the XML must be part of the POST body. Submitting the XML as a URL parameter does not allow encoding to be specified. The encoding is specified as part of
the Content Type in the HTTPS header (for example, Content-Type: text/xml;charset=UTF-8). If you specify an encoding attribute within the XML (for example, <?xml version="1.0" encoding="UTF-8"?>), the Watson Campaign Automation ignores it. If you submit XML through the POST Body, but do not include the charset in Content Type, the organization default is used. If you submit a POST where the body contains content, ensure that Content-Length is specified in the HTTPS header. If passing the XML as a URL parameter (xml=), you must URL encode the XML and specify that it is URL encoded (Content-Type: application/x-www-form-urlencoded).
API requests pass either the OAuth based Access Token in the request's header or the legacy Javaâ„˘ Session ID (jsessionid) as a path parameter in the URL string.
Note: Be sure to use https and append the path parameter to the URL by using a semicolon, as opposed to the question mark separator used for appending query parameters to a URL. Do NOT pass the legacy jsessionID as a form parameter rather than a path parameter.