HTTP

Getting Started

This document will guide you through obtaining ABC experiment results via the HTTP API. If you haven't done so already, please follow the instructions in this document to create an ABetterChoice project. For demonstration purposes, we've created a new project identified by the project ID 78, as depicted below. You can locate its API key under the settings tab, which will be utilized in subsequent steps.

HTTP API request

Authentication

To authenticate the caller, the following information needs to be carried in the request header for each HTTP API request:

Header	Description
X-Ak	The name of your secret key.
X-Et	The Unix timestamp for this request.For example, the Unix timestamp 1713841639 represents "2024-04-23 11:07:19".
X-Es	The signature for this request.

Signature

The way to calculate the signature is shown below:

1. Firstly, you should get your secret key name and your API token.
2. Secondly, get the current Unix timestamp.
3. Finally, computes the MD5 checksum of the input byte slice. The input to the MD5 function is the combination of the token, the app key ak, and the timestamp et. Then Converts the MD5 checksum (which is a byte slice) to a hexadecimal string.

# Use the shell script get a signature
# for macos
ak="your_secret_key_name" # replace the value with your own secret key name
token="your_api_token" # replace the value with your own api token
et=$(date +%s) # get current Unix timestamp
echo -n "${token}${ak}${et}" | md5 # caculate the signature

Experiments

1.Create Experiments

If you haven't done so already, please navigate to the console and create a new experiment by following our guide on how to create an experiment.

For instance, we have created a new experiment named experiment_for_button within the layer layer_on_landing_page. This experiment involves two parameters: a string type color and an integer type size. Please note that before fetching the experiment result for a specific user online, we need to allocate some traffic and start the experiment, which will change its status from Setup to Running.

2. Fetch Traffic Splitting Results

Parameter Descriptions

Parameter	Description
project_id	The ID of the project, as shown in the example above.
unit_id	A unit ID can be a user ID, a session ID, or a machine ID. The ABC SDK consistently assigns a unit ID to the same experiment group.
profile	Optional. User profile tags. You may need this information for user targeting in experiments.
filter_options.layer_keys	Optional. Names of the layers to be retained.
filter_options.experiment_keys	Optional. Keys of the experiments to be retained.

Request Example

# Get all experiments in which the user with ID user_id_1 participated in project ID 78

ak="your-secret-key-name" # replace the value with your own secret key name
token="your-API-token" # replace the value with your own api token
et=$(date +%s) # get current Unix timestamp
signature=$(echo -n "${token}${ak}${et}" | md5) # caculate the signature

curl --location --request POST 'https://openapi.abetterchoice.ai/abc/get_experiments' \
    -H "Content-Type: application/json" \
    -H "X-Ak: $ak" \
    -H "X-Et: $et" \
    -H "X-Es: $signature" \
    -d '{
        "project_id": "78",
        "unit_id": "user_id_1"
    }'

# Filter by layer
# Get experiments in which the user with ID user_id_1 participated in the layer layer_on_landing_page under project ID 78
curl --location --request POST 'https://openapi.abetterchoice.ai/abc/get_experiments' \
 -H "Content-Type: application/json" \
 -H "X-Ak: $ak" \
 -H "X-Et: $et" \
 -H "X-Es: $signature" \
 -d '{
    "project_id": "78",
    "unit_id": "user_id_1",
    "filter_options":{
        "layer_keys":["layer_on_landing_page"],
        "experiment_keys":[]
    },
  "profiles": {"age":{"user_attrs":["18","19"]}}
}'

Response

The key of the map is the layer name, and the value of the map shows the traffic splitting results on each layer. Note that if the user is not allocated to any active experiment in a layer, they will fall into a default experiment with group id -1.

{
    "ret_code": 100,   //response code, see details below
    "msg": "",         //error message
    "exp_data": {      //experiment info
            "layer_on_landing_page": { // layer name
                "experiment_key": "experiment_for_button", // experiment ID
                "group_id": 8942824,       // numerical group ID
                "group_key": "Treatment_A",  // group name
                "params": {      // parameters of the experiment    group
                    "color": "blue",
                    "size": "20"
                }
             },
            "layer_with_no_experiment": { // layer name
                "experiment_key": "default", // default experiment ID
                "group_id": -1,       // default numerical group ID
                "group_key": "default",  // default experiment group name
                "params": {}
             }
    }
}

Feature Flag

Get feature flags

If you don't know how to create a feature flag, please refer to this document.

Once you have created feature flags, you could get them as follow:

Parameter Descriptions

Parameter	Description
project_id	The ID of the project, as shown in the example above.
unit_id	A unit ID can be a user ID, a session ID, or a machine ID. The ABC SDK consistently assigns a unit ID to the same experiment group.
feature_names	The names of the features to be looked up.
profile	Optional. User profile tags. You may need this information for user targeting in experiments.

Request Example

Feel free to copy the blew shell script to your terminal and replace the ak and token with your secret key name and API token. The project and feature flags in the request body should have already been created, or you may get an error "NOT FOUND".

# Get the feature flags named "my_colour" and "my_button_type" in project 78 that are hit by the user with the id "user_id_1" and age 18.

ak="your-secret-key-name" # replace the value with your own secret key name
token="your-API-token" # replace the value with your own api token
et=$(date +%s) # get current Unix timestamp
signature=$(echo -n "${token}${ak}${et}" | md5) # caculate the signature

curl --location --request POST 'https://openapi.abetterchoice.ai/abc/get_feature_flags' \
 -H "Content-Type: application/json" \
 -H "X-Ak: $ak" \
 -H "X-Et: $et" \
 -H "X-Es: $signature" \
 --data-raw '{
    "project_id": "78",
    "unit_id": "user_id_1",
    "feature_names": ["TEST"],
    "profiles": {"age":{"user_attrs":["18"]}}
}'

Response

The key of the map is the feature flag name, and the value of the map shows the feature flag value and relative experiment. Note that if the feature flag is not related to any experiment, the field "relative_experiment" will return null.

example1: Feature flags bind with experiments

{
    "ret_code": 100,   //response code, see details below
    "msg": "",         //error message
    "data": {      // feature flag data
            "my_colour": { // feature flag name
                "name": "my_colour", // feature flag name
                "value": "red",       // feature flag value
                "relative_experiment": { // relative expreiment info
                        "group_id": 76178323141,
                        "group_key": "experiment_for_color",
                        "exp_key": "control_group_for_color_experiment",
                        "params": {
                            "my_colour": "red"
                        }
                    }
                },
 "my_button_type": { // layer name
                "name": "my_button_type", // default experiment ID
                "value": "simple",       // default numerical group ID
                "relative_experiment": { // relative expreiment info
                        "group_id": 61783231414,
                        "group_key": "experiment_for_button",
                        "exp_key": "control_group_for_button_experiment",
                        "params": {
                            "my_button_type": "simple"
                        }
                    }
                 }
    }

}

example2: Feature flags do not bind with experiments

{
    "ret_code": 100,   //response code, see details below
    "msg": "",         //error message
    "data": {      // feature flag data
            "my_colour": { // feature flag name
                "name": "my_colour", // feature flag name
                "value": "red",       // feature flag value
                "relative_experiment": null
            },
 "my_button_type": { // layer name
                "name": "my_button_type", // default experiment ID
                "value": "simple",       // default numerical group ID
                "relative_experiment": null
           }
    }
}

Return Code

ret_code	meaning
100	success
101	no permission
102	traffic limit
103	required project id
104	server error
105	server error
0	unknown