Limitations of how the Watson Campaign Automation APIs can be used.
Watson Campaign Automation has a robust API that handles the automation of most actions available through the Watson Campaign Automation UI, such as adding new contacts or sending email campaigns. However, we place limits on the way our customers use our APIs to ensure that we provide the highest level of service and performance to all of our customers.
Concurrent requests and active sessions
Concurrent requests and what to expect.
API users of the legacy authentication (see more in the section on “Legacy Authentication Method”) must maintain no more than 20 active login sessions per Org at any time. To optimize the use of active sessions, make sure that your application uses the Logout API to release an active session when you are finished interacting with the API. This prevents lingering sessions that are no longer in use from blocking the creation of new active sessions. Inactive sessions that are not terminated properly with the Logout API can remain active for several minutes. All users of the Watson Campaign Automation XML API are strongly encouraged to use OAuth 2.0 authentication. This token-based authentication model is much more flexible by allowing for the reuse of access tokens and eliminating the need to generate a high number of unique and active sessions.
API users must maintain no more than 10 concurrent requests per Org to the API servers during a specific time frame. Maintaining more than 10 concurrent requests can be subject to blocking by the Operations team. In most cases, a single connection to the API is adequate to handle all of your processing needs. Consider one of the asynchronous/batch APIs when nearing the maximum number of connections. These APIs are much more efficient at moving large data sets rapidly in and out of Watson Campaign Automation. Some robust asynchronous APIs are ImportList, ExportList, and RawRecipientDataExport.
Batching actions within a single XML envelope
Requirements for batch actions.
All submissions to the Watson Campaign Automation API must contain one, and only one, action per each XML Envelope. Batching multiple actions within a single request is unsupported and can result in throttling or suspension of access to the API by the Operations team.
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 Watson Campaign Automation is not available due to a maintenance outage, the following XML is returned:
<Envelope> <Body> <RESULT> <SUCCESS>false</SUCCESS> </RESULT> <Fault> <Request/> <FaultCode/> <FaultString> <![CDATA[The system is currently down for maintenance.]]> </FaultString> <detail> <error> <errorid>52</errorid> <module/> <class>SP.Admin</class> <method/> </error> </detail> </Fault> </Body> </Envelope>
Forming XML API requests
The interfaces to 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:
<Envelope> <Body> <…Content…> </Body> </Envelope>
To pass parameters, list each parameter as a child element of the operation element, as shown.
<Envelope> <Body> <SendMailing> <MailingId>211191</MailingId> <RecipientEmail>firstname.lastname@example.org></RecipientEmail> </SendMailing> </Body> </Envelope>
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″?>), 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.