Experiment REST API

Welcome to the Data Cortex Experiment API.

This API allows clients to request the current experiments that they should be enrolled in.

API Endpoint

All calls are made on the experiment endpoint:

https://api-experiment.data-cortex.com

Request

Calls to the API are made with a POST to the API endpoint. The application should make sure to request with Accept-Encoding: gzip to minimize data transferred from the response.

POST /<org>/1/experiment_status

<org> - string - Should be replaced with the organization short name.

Request Parameters

The request should contain a JSON body. The client should be sure to set the the Content-Type header to "application/json". Arguments are required unless noted otherwise.

api_key - string - The api key specific to this application. Applications can have more than 1 API key, but can not be shared between applications.

app_ver - string - The version of the application. 16 character maximum.

user_tag - string - (optional) A cross device identifier for the user, e.g. Facebook ID, Twitter ID, Google ID. If this is sent the user will be enrolled in the same experiment variants on multiple devices.

device_tag - string - A unique ID for the device. IDFA for iOS, MAC Address for Android, a randomly generated value for the browser stored in a cookie or localStorage. 62 character maximum.

device_type - string - type of device. 16 character max. e.g.

    desktop, iphone, iphone3g, iphone4, iphone5s, iphone5c, android

os - string - The OS of the device. 16 character max. e.g.

    ios, mac, windows

os_ver - string - The OS version. 16 character max.

browser - string - (optional) The browser in use. 16 character max.

browser_ver - string - (optional) The browser version. 16 character max.

country - string - (optional) The uppercase 2 letter ISO 3166-1 alpha-2 country code of the device location. Should not be included if the application can not determine the device location. If application does not pass in device location, location will be determined by geo-mapping the device's ip address.

language - string - (optional) The lowercase 2 letter ISO 639-1 language code.

new_gate_list - list of strings - (optional) A list of new experiment names the player has unlocked by crossing the gate. On startup the game can make a request without a set of gates to get a list of all experiments that the user has previously unlocked and the variants they are currently assigned. If empty or missing, the call will return all previously entered experiments and their current variants.

Response

The API responds with the following depending on the result.

Success

Returns the list of experiments and variants the device is enrolled in given the request parameters. The request will be gzip encoded if the client requests with Accept-Encoding: gzip.

 HTTP/1.1 200 OK
 Content-Type: application/json
 Date: Sun, 10 Nov 2013 04:24:17 GMT
 
 {
  "experiment_list": [
    { 
      "experiment": "game_feature_1",
      "variant": "blue_background"
    },
    { 
      "experiment": "game_feature_2",
      "variant": false
    },
    { 
      "experiment": "game_feature_3",
      "variant": "extra_energy"
    }
  ]
 }

false indicates the user is still in Variant 0, the control group. A string indicates the user is in the named variant.

Bad Request

Bad request. Check with Data Cortex documentation and verify that you are sending all required fields and valid data types in those fields.

 HTTP/1.1 400 Bad Request

Auth Failure

Bad API key. Check with Data Cortex and verify your API key. Productions clients should treat this as a fatal error.

 HTTP/1.1 403 Forbidden

All other error codes.

Internal server error. Clients should treat these as soft errors.

 HTTP/1.1 500 Internal Server Error