doc

Connect

Burt Connect lets you join additional data into the Burt platform. The additional information may be of the nature which is impractical or sensitive to expose and/or send directly via the Burt tracking from the client. Working with Burt Connect consists of two parts:

  • Configure the tracking to send a connection with a given scope, name, and value tuple.
  • Import data into Burt Connect with the same scope, name, and value, which can then be joined onto objects with a matching tuple.

Examples of data which can be connected include: campaign revenue, visitor demographics, and article metadata.

Importing data into Burt Connect consists of issuing requests to a REST API. This API can also be used to query imported data, as well as monitoring status for imported data. The following text illustrates an example.

Example: Article metadata

The (fictional) company Acme Corporation has metadata about articles stored in a database and want to enrich the Burt data with this data. The data consists of the author, content grouping and article length for each article.

On the website, a connection has been set up to send a connection along with every page view, like so

window.burtApi.connect('acmecorp.content', 'article-id', articleId)

where articleId is a variable containing the article ID, for example 1337 or 42. Given this setup, Acme Corp. can import the additional article data into Burt Connect to make this data available. In the following example, our reference Connect client Koppel is used to import data:

articles = {
  "42" => {
    "author" => "Bobby B",
    "group" => "News",
    "length" => 437
  },
  "1337" => {
    "author" => "Lucy L",
    "group" => "Science",
    "length" => 843
  },
  # ...  
}

connect = Koppel::Client.new(*credentials)
connect.send_items("acmecorp.content", "article-id", articles)

Endpoints

All endpoints require request signing, which is detailed in the Signing Requests section. However, if you use our Ruby client Koppel you do not need to worry about request signing.

For all requests, the :account parameter is a unique identifier for your account, consisting of a 12-character string. You will obtain it from us along with the secret key required for signing.

All responses from the API will have the content-type application/json. Any requests with a body should also be of this content-type, with the body consisting of a JSON string.

POST /v2/connect/:account/:scope/:name

Imports data into the platform.

Parameters

  • scope – The scope in which to import data into
  • name – The name in which to import data into

Body parameters

  • items – A JSON object with one or many items to import. Each key of this object will be used as the value key for the imported data.

Example body

{
  "items": {
    "42": { "author": "Bobby B", "length": 476 },
    "1337": { "author": "Lucy L", "length": 875 },
  }
}

Responses

  • 201 – The items were accepted.

GET /v2/connect/:account/:scope/:name/:value

Queries an item from the platform.

Parameters

  • scope – The scope in which to import data into
  • name – The name in which to import data into
  • value – The unique value which is to be queried

Responses

  • 200 – The requested item was found and returned. The body will be the item as imported into the platform. E.g. { "author": "Bobby B", "length": 476 }
  • 404 – The requested item was not found.

GET /v2/connect/status/:account

Queries the status for the account.

This endpoint is intended for diagnostic or monitoring purposes. It exposes a status object for each scope and name combination that data has been imported for. Each such status will contain information about how many items have been imported or updated. Additionally, each such status contains information about how many hits and misses when trying to query the imported data.

Please note that the figures in the status objects returned by this endpoint are conservative, i.e. there is no guarantee that all transactions with the connect API are recorded in the status objects.

Responses

  • 200 – A status was found. The body is an array of statuses, one for each scope and name combination into which data has been imported. E.g.
    [
      {
        "scope": "acmecorp.content",
        "key": "article-id",
        "updated_count": 5,
        "updated_at": 1448399737,
        "miss_count": 3,
        "miss_at": 1448399778,
        "hit_count": 5,
        "hit_at": 1448399738,
        "changed_count": 2,
        "changed_at": 1448399737
      }
    ]

Signing requests

All API requests to Burt Connect must be signed. The signing method uses HMAC-SHA1 and works very similarily to the AWS APIs. To create a signature for a request you need to create a canonical representation and sign it using your secret key.

The signature is set as a HTTP request header and is verified server-side. For any request with an invalid signature, the API will respond with a response code of 403. The response body can be examined for possible additional information. The header is set using the following format:

Authorization: Burt HMAC-SHA1 $account:$signature

where $account is the account key (see Endpoints) and $signature is the generated signature.

The canonical representation of a requests is created like this:

components = [
  http_method,
  http_date_header,
  path,
  content_type,
  content_digest,
  canonical_query_string
]
canonical_representation = components.join("\n")

Please note that there is no trailing newline.

  • http_method is GET, POST, etc., always in upper case
  • http_date_header is the value of the Date header, i.e. a date formatted according to RFC2822 section 3.3. In Ruby you can do require 'time'; Time.now.rfc2822.
  • path is the request path, i.e. everything after the domain/port, including the initial / up until the query string or the end of the URL if there is no query string.
  • content_type is the value of the Content-Type header and should be an empty string for requests without bodies (e.g. GET and DELETE).
  • content_digest is the MD5 hash of the request body, and should be an empty string for requests without bodies (e.g. GET and DELETE).
  • canonical_query_string is the query string with the parameters in alphabetical order (e.g. a=1&b=2). Duplicate parameters (e.g. foo=1&foo=2 are not supported and will lead to signature mismatches).

The signature is then created by signing the canonical request representation with your secret key using HMAC-SHA1 and encoding the result as Base64. This is how you would do it in Ruby:

secret_key = …
canonical_representation = …
signature = Base64.encode64(OpenSSL::HMAC.digest('sha1', secret_key, canonical_representation)).chomp

and in Java:

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;

String secretKey = …;
String canonicalRepresentation = …;
Mac mac = Mac.getInstance("HmacSHA1");
SecretKeySpec keySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA1");
mac.init(keySpec);
byte[] signatureBytes = mac.doFinal(canonicalRepresentation.getBytes());
String signature = DatatypeConverter.printBase64Binary(signatureBytes);

Finally you use this signature in the Authorization header of your request, and you set the Date header to the same date as you used in the signature:

http_date_header = request_time.rfc2822
signature = # …
headers = {
  'Date' => http_date_header,
  'Authorization' => "Burt HMAC-SHA1 #{account_key}:#{signature}",
  'Content-Type' => content_type,
}

Please note that the Content-Type header should only be set when the request has a body.




Back to Top