Integration & Setup

  1. Home
  2. Integration & Setup
  3. Entwickler APIs
  4. Testing API
  5. How to use the API

How to use the API

API Components

The REST API provides functionality in the following areas:

  • Management: Create, retrieve, update and delete projects and all related entities like pages, conversion goals and personalization rules.
  • Reporting: Retrieve data gathered in projects (mostly numbers of impressions and conversions on a daily basis) to visualize them in charts or create custom reports.
  • Delivery: Allows to retrieve personalized and optimized content from the API and to send conversion events in order to optimize applications with personalization and A/B testing via REST communication (vs. Javascript based delivering of content via the etracker Tag).

Business Objects

The Testing API deals with the following set of business objects.

Account

Represents a user account, where the user identifies herself with a combination of email/password or api-key and api-secret. Users can create projects inside an account.

Project

A project is a container to deliver views to visitors. This can happen by conducting an A/B-test or simply by delivering

Decisiongroup

A decisiongroup represents a sub-project. It is used for „Teaser Tests“ and groups decisiongroups together. A project of type „TEASERTEST“ may contain multiple decisiongroups, which in turn can contain multiple decisions. For all other types of projects, decisions are direct children of the project itself.

Decision

A decision is one out of several possibilities to display a piece of content. In a typical project one decision would represent the original version of a web page (also called „the control“), while other decisions represent variants of the page. In an A/B test, the original and variant „decisions“ are delivered to users in a randomized manner, while using personalization they could be delivered depending on visitor properties.

Goal

A (conversion-) goal helps to decide which of a project’s decision is the optimal one. A conversion goal could be something like

  • A page URL which has been requested by a visitor
  • The fact that the visitor has clicked some link and thus „engaged“ with the website
  • A special Javascript function that has been called from the web page
  • etc.

By definition the decision with the best conversion rate is the best.

Rule and Rule-Condition

A rule is a set of rule conditions and is used to deliver personalized decisions. A condition is a single statement like

  • Visitor traffic source is paid search
  • Visitor device is mobile
  • etc.

A rule is a named set of conditions that combines conditions with AND or OR. It can be tied to a decision, so that a decision is only delivered if the rule is valid.

Trend

A trend is an array of data points, representing user actions in a project. Typically a trend contains impressions, conversions and conversion rates on a given day in a given period of time.

Groups and Permissions

Each consumer using the API is assigned to one of the following groups:

  • API-Tenants: This role allows to create and manage accounts, including deleting the account. When an account is created, an API-client is created automatically by etracker. The API-tenant role has all permissions of the API-clients it has created.
  • API-Clients: This role allows to manage one account and all nested resources like projects, variants, goals, rules etc. it is not possible to delete the account, though.

An API consumer is identified during authentication with an API key and –secret. Each API-consumer can be assigned to only one role, meaning:

  • Be an API-tenant
  • Be an API-client of one account.

API-tenants may read, update and delete all resources that they created themselves or their clients. API-clients may read, update and delete all resources that they created, and they may read and update parts of their own account information.

Authentication

API consumers authenticate themselves via Basic Authentication, which means that an API-key and API-secret of the user have to be passed with every request in the HTTP Authorization header.

The Login Ressource

The API provides one resource (login) that does not represent a business object but is mainly to support authentication and login functionality. It validates API-key and API-secret and returns the internal account-ID of the API user which is necessary for subsequent API calls. The resource has to be called in the following way: POST /login with an object in the POST body that contains the following attributes:

FieldDescription
usertypeDepicts wether an API client or tenant accesses the API:
• api-client
• api-tenant
apikeyThe API-key
apisecretThe API-secret

API URLs and Versioning

The REST API is used by HTTP requests to URLs which are built up by the following parts: <protocol>://<server and path>/<version>/<resource>/

FieldDescription
protocolOnly SSL is allowed as protocol. Calls to http:// will result in a 403 Forbidden error
server and pathThe server name and base path, typically www.blacktri.com/api/
versionWe use v1, v2... to version the API. The current version number is v1.
resourceThe actual resource that the call refers to. The specification focusses on resource names only and leaves out the rest of the API URL.

Example: GET https://www.blacktri.com/api/v1/account/4711/project/2435/

Operations and Ressources

According to REST best practices, the Testing API uses HTTP methods as operations that act on business objects defined by URL „resources“. The following operations are supported:

  • GET: retrieves informations on an object.
  • POST: used to create objects or, more general, for operations that are not „idempotent“, meaning they change the system state after each operation.
  • PUT: used to update objects. An object must exist before it can be updated.
  • DELETE: used to delete objects.

Resources specify business objects via the URL. Example: /account/4711 Refers to the user account with ID 4711.

Naming and Ressources

Resources refer to business objects. They are named in singular to represent a single object. When used in plural, they refer to a collection of objects. To identify a single object, an ID is added to the URL following the resource. /account/ A single user account. /account/4711 Account with ID 4711. /account/4711/project/1324 Project 1324 of user 4711. /account/4711/projects List of all projects of user 4711

CRUD Operations

Some actions are represented by a resource name in case GET, POST, PUT or DELETE are not appropriate operations. Example: POST /account/4711/project/1234/goal/1654/convert By this request a client informs the system that a conversion for goal 1654 has happened and shall be tracked.

Passing Data Objects

With POST and PUT typically a data object is passed which represents a resource that shall be created or updated.

  • Depending on the role of the API consumer some objects attributes can be read-only. If a read-only attribute is passed in a POST or PUT operation (e.g. creation date and time of the resource), an error is returned and the complete operation is discarded.
  • PUT can be used for partial updates, meaning not all attributes of an object need to be contained in the data object. Only those attributes that are contained will be used in the update then.
  • In case a PUT operation is used for a resource which has not been created yet with POST, an error will be raised.
  • Objects can have mandatory attributes. If these are not passed in the data object of a POST operation, an error will be raised.

JSON as Data Format

As of now, only JSON is supported as the data format in request and response

Nested Objects

There is a hierarchy of objects which the API refers to. The way this hierarchy is reflected in API calls is depending on the specific operation with regards to the following 2 aspects:

  • How can nested objects be read? By directly accessing them via a resource URL, or as part of the response of the parent object?
  • How can nested objects be created and updated respectively?

Direct Access via URL

Nested objects can always be directly referenced as a resource URL as depicted above: GET /account/4711/project/1234/variant/88364 Read data of variant 88364 POST /account/4711/project Create a new project etc.

GET Operations and Collection Attributes

This would return an object of type project which has an attribute variants that contains all variants of the project.

POST and PUT Operations and Collection Attributes

Some resources allow to pass objects containing nested child objects in a collection attribute. In such a case the following rules apply:

  • When nested objects are passed as part of a POST operation, the parent object is created first and then the child objects.
  • When nested objects are passed as part of a PUT operation, the parent object is updated together with the child objects.
  • When the collection attribute in a PUT operation does not contain all existing child objects of an object, the child objects not in the collection will be deleted.

REST Responses and Error Handling

For every request the Testing API provides an HTTP response status in some cases (depending on the specific operation) an HTTP header and a JSON formatted response data object.

Successful POST Operations

When a resource has been created from a successful POST operation, the following response is created:

FieldContentDescription
HTTP Status-Code201 Created
HTTP-Location-HeaderLocation:The location header contains the URL of the new resource, so a GET request can read the details of the new resource.
If nested objects have been created together with the POST, nothing is returned for them.
Response-BodyThe response body is empty.

Successful GET Operations

If a resource can be successfully read, the following response is created:

FieldContentDescription
HTTP Status-Code200 OK
Response-BodyThe response body contains the data object.

Successful PUT Operations

When a resource has been sucessfully updated by a PUT operation the following response is created:

FieldContentDescription
HTTP Status-Code204 No content
Response-BodyThe response body is empty.

Successful DELETE Operations

When a resource has been sucessfully deleted by a DELETE operation the following response is created:

FieldContentDescription
HTTP Status-Code204 No content
Response-BodyThe response body is empty.

Error Handling

In case of an error, the HTTP status code has a specific value and the returned data object contains information on the error.

FieldContentDescription
HTTP Status-Code<3 digit HTTP error code> Status code and HTTP reason (a short error message) are depending on the error.
Response-BodyJSON encoded error object, see below.

Error Object

FieldContent
codeDetailed error code. Since there is a limited number of 3 digit HTTP codes, this codes allows to qualify the exact error.
messageClear text error message.

List of API Errors

CodeHTTP CodeMessage
400003400Invalid field/s:
400004400Invalid value supplied for : ""
400100400Mandatory field/s for account missing:
400101400Read-only field/s for account not allowed to be set:
400103400Invalid field: not allowed to change publicid
400104400Unique constraint violation: publicid must be unique
400105400Unique constraint violation: email must be unique
400200400Mandatory field/s for project missing:
400201400Read only field/s for project not allowed to be set:
400300400Mandatory field/s for decision missing:
400301400Read only field/s for decision not allowed to be set:
400400400Mandatory field/s for rules missing:
400401400Read-only field/s for rules not allowed to be set:
400500400Mandatory field/s for rule conditions missing:
400501400Read-only field/s for rule conditions not allowed to be set:
400600400Mandatory field/s for goals missing:
400601400Read-only field/s for goals not allowed to be set:
401000401Authentication error: Invalid api-key or api-secret
403006403No permission for feature/s:
403102403Authorization error, no permission to create account
403103403Authorization error: Access to account denied
403203403Authorization error: Access to project denied
404001404Resource not found:

Qualifying GET Operations

Some GET operations allow to further qualify the response, e.g. to filter it or control wether nested objects shall be contained in the response or not. Which qualifiers are available is specified in the documentation.