Analytics Exchange V1 REST API
The Analytics Exchange V1 REST API is a web service that you can use to administer users, audit content, and analytics. Use the API to integrate Analytics Exchange with external applications using the Hypertext Transfer Protocol Secure (HTTPS) protocol.
Analytics Exchange API connection details
Base URI
Connect using the following base URI: axServerHostname:443/restv1. For example, https://axcore.example.com:443/restv1.
Requests and protocol
The API requires HTTPS connections for all communications between the client application or script and server. Request and response data is sent in XML format.
Client applications connect to the API by sending an HTTP request to the appropriate URI with standard HTTP methods. Each request is independent of any other request, and contains all of the necessary information to complete the request.
Authentication
The API uses the HTTP Basic Authentication method and requires a user name and password submitted as a single string username:password.
Content (MIME) type
When using the POST method to send XML data to the APIs, you must specify the application/vnd.com.acl.ax.analyticjob+xml content type.
General request syntax
The examples provided for each request use the CURL command line tool to illustrate their usage.
curl -k -o c:\curl\getspecifiedactivity.xml -X GET --user ACL\AXAPIUser:Password https://ax.example.com:8443/restv1/activity/769e04fc-7ebb-4f1b-9359-221c2185dcb2
The examples for POST API methods include the XML payload to post in the command line. You can also specify this information in a separate file using the following syntax, where the name of an XML file in the same directory as curl.exe is specified instead of the XML syntax:
-d "@restore.xml"
Note
If you are including extended characters in the XML syntax, such as Chinese characters in an engagement name, you must use an external .xml file because these characters cannot be entered on the command line.
Response status codes
The APIs return standard HTTP response codes:
| Code | Description |
|---|---|
| 200 OK | Success. |
| 201 Created | Success. Includes location header on create operations. |
| 204 No Content | Success. Returned on success with no further information, usually by update operations |
| 400 Bad Request | Usually a validation error indicating the submitted data is formatted incorrectly, check response for error information. |
| 403 Forbidden | BASIC authorization credentials supplied don't have the system admin role. |
| 404 Not Found | Error indicating the request was probably a bad URI, indicating the specified resource doesn't exist. |
| 409 Conflict | Error when creating a resource when a resource with the same name already exists. On user creation, also possibly indicates that the user license limit has been reached. If running an analytic, could indicate a specified parameter set is not compatible. |
| 415 Unsupported media type | Error returned if a POST request specifies the wrong MIME type. |
| 500 Internal Server Error | Something unexpected happened on the server. Check the server logs for more info. |
Product terminology
In version 5.0 of AX Server, the product terminology in Analytics Exchange changed. However, terminology in the AX API did not change from AX Server version 4.x so that existing 4.x API client applications can continue to be used with AX Server version 5.x and later.
| Version 5.x and later | AX API | Description |
|---|---|---|
| Collection | Engagement | The top level organizational container of AX Server |
| Folder | Activity | The second level organizational container of AX Server |
| Analysis app | Analytic project or Analytics project | An Analytics project that contains one or more analytics. |
| Analytic | Analytic script | A single Analytics script that has an analytic header allowing it to run on AX Server |
