Skip to main content
Adaptive Insights
Knowledge and Support - Adaptive Insights

Request and Response Message Formats

Request and Response Message Formats

The Request

Every API method in the Adaptive API expects the XML document in its body to have a structure that looks like the follow­ing:

     <?xml version='1.0' encoding='UTF-8'?>
     <call method="exportData" callerName="a string that identifies your client application">
        <credentials login="sample@company.com" password="my_pwd"/>               
        method specific data goes here
     </call>

Here is a description of each of the relevant lines:

  1. This line indicates that the subsequent data is XML encoded in UTF-8.

  2. The <call> tag indicates which API method is being called using its method attribute. In this example, the API method is exportData. In addition, callerName is a required attribute on the <call> tag. It identifies your client applica­tion to the system and is used for identification purposes when troubleshooting and logging.

  3. Every API method needs to authenticate the user making the call. This is typically done by providing a login name and password. Other attributes are allowed to be specified here. See the documentation for each API function for more details on credentials.

  4. Some API methods require additional data in the request. For example, the exportData method requires some crite­ria describing which time periods, accounts, levels, etc, should be used when retrieving its data. This portion of the request will vary from method to method.

  5. This is the closing tag for the call tag on line 2.

The Response

Every response from an API method will have the following structure:

      <?xml version='1.0' encoding='UTF-8'?>
      <response success="true">
        <messages>
           <message key="modeled-import-success">Personnel import successful. Rows imported: 100</message>
        </messages>
        <output> 
          ... method output ... 
        </output>
      </response>

Here is a description of the relevant lines:

  1. Similar to the request, this line indicates the subsequent data is formatted as XML and encoded in UTF-8.

  2. Each response is enclosed in a <response> tag. If the request was successful, the success attribute on the response tag is set to true. If the request was unsuccessful, the success attribute is set to false.

  3. Many API calls will return this optional <messages> block containing a list of server-generated messages. This block may not appear if the server had no messages to return in response to the call. Error messages will always appear within the messages block.

  4. Each message within the messages block has a key attribute identifying the type of message being transmitted. The message tag also contains the text of the message from the server, including any return values, status values, or other standalone metadata about the success or failure of the request. A response may contain an unlimited number of message tags.

  5. The closing messages tag.

  6. The actual output from the API method call, if any is returned, is enclosed in an <output> tag.

  7. The actual output from the API method call will appear here. This output varies depending upon which method was called.

  8. The closing output tag.

  9. The closing response tag.

 

  • Was this article helpful?