Introduction

Analytics Connect API

Base URL

Connect API request URLs take the following base path:

https://connect.applixure.com/v1/

Authentication

Connect API uses API credentials in the form of username + password keypair (HTTP Basic Authentication over TLS) for all authentication.

You can generate API credential keypairs from the Web UI. API credentials can be created on per environment basis or at the Applixure account -level to access data in all environments within that same single set of credentials.

📘

How to use HTTP Basic Authentication credentials?

If you are using dedicated REST client application or library for accessing Applixure Connect API, there usually exists a way of specifying authentication being used ("HTTP Basic Authentication") and supplying username and password to the client's dedicated fields as such, and not having to worry about how these values will be used at the HTTP level.

However, if you use tools (like curl or wget) to supply raw HTTP header values as part of the GET/POST request, you have to perform the exact encoding manually if Authorization is one of the headers supplied by hand.

With Basic Authentication scheme, your key's username and password must be transformed and provided as part of the Authorization HTTP header line in the following format:

Authorization: Basic CREDENTIALS

In this format, username and password (the CREDENTIALS part of the syntax) are not listed literally as is but first needs to be turned into valid encoded format by

a) first concatening both together with colon in-between (username:password) and then
b) encoding the concatenated text with Base64 encoding

Resulting Base64 -encoded string should then be used as CREDENTIALS -part in the above example syntax.

You can use offline tool of your choice to perform Base64 encoding (recommended for security) or use any number of online -based Base64 encoders/decoders such as one at https://www.base64encode.org/.

You can read more about HTTP Basic Authentication here.

Data formats

Queries to the Connect API returns JSON formatted data as payload.

Endpoints requiring data in the submitted body expects JSON formatted data.

📘

Please note: access to the data using Connect API is presently read-only.

Backwards and forwards compatibility

From time to time, Applixure may add new fields to the existing objects returned from the API, add new API endpoints or add new optional parameters to the existing endpoints. Also the ordering of the fields in the JSON objects should not be expected to stay fixed.

As these potential changes can be considered backwards compatible changes, any consumer of the Connect API are expected to implement parsing accordingly.

We will not be making any backwards-incompatible changes to existing APIs, such as removing already-established attributes. In case such changes are deemed necessary, new version of API will be introduced.

If new versions of the API will be introduced, Applixure will not guarantee that any potentially new type of object introduced into data model will be backported into older - still active - versions of the API.

Error handling

For all normal API responses the returned JSON object includes field called ApiCallSucceeded which will tell if the call to the endpoint succeeded and actual data is available.

In case there's logical error in the call, this field will be set to value false, and further error information is returned in additional fields called ApiCallError and ApiCallErrorDescription:

{
  "ApiCallSucceeded": false,
  "ApiCallError": "InvalidRequest",
  "ApiCallErrorDescription": "Invalid environment id specified"
}

Additionally, normal HTTP -level errors should be expected for following conditions:

Typical workflow

When accessing Connect API, a typical workflow for accessing data is to first query all the environments the credentials give access to.

You can get list of environment using API endpoint for retrieving the list of environments:

{
  "ApiCallSucceeded": true,
  "Environments": [
    {
      "EnvironmentId": "7b884896-f8e9-4372-85f2-de75ad8d71d1",
      "Name": "DEMO"
    }
  ]
}

Using returned list (array) of environment IDs, further API calls can be constructed using the environment's ID as a identifier in the URL for accessing data from specific environment.

Please refer to the available API endpoints using the Reference Docs.

To learn more about data model for objects returned from Connect API, refer to Applixure data model.