etracker
Analytics Editions / Pricing Live-Demo
etracker
Optimiser Editions / Pricing Live-Demo
Pricing For Agencies Support

How to use the API

  • 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).
    The Testing API deals with the following set of business objects.
    • A project is a container to deliver views to visitors. This can happen by conducting an A/B-test or simply by delivering
      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.
      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.
      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.
      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.
      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.
      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.
    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.
    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 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
    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/
    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.
    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
    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.
    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.
    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.
    • 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.
      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.
      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.
      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.
      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.
      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.
      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:
    For creating, reading, updating and deleting objects the operations and resources are used as depicted in the following examples. POST /account Create a new account and obtain a reference to it in the response. GET /account/4711 Returns an object for account with ID 4711. PUT /account/4711/ Update account 4711 using the data passed in the request body. DELETE /account/4711/project/1234 Delete project 1234. POST /account/4711/project Create a new project object for account 4711. GET /account/4711/projects Returnd all projects of account 4711.
    As of now, only JSON is supported as the data format in request and response
    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?
    • 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.
      This would return an object of type project which has an attribute variants that contains all variants of the project.
      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.
    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.

Need help?
Our friendly, knowledgeable support engineers are here for you.