Complete RESTful API

Here we describe the details of the REST API endpoints that are provided by StreamingBandit. Note that, with the exception of the two Core API calls, all the calls require authentication (for details see the Login API specs below).

Core API

The core API contains the getaction and setreward calls (or, alternatively the decision and summary step of a bandit policy).

GET (?i)/getaction/(?P<exp_id>w+)

Get an action given a context for a specific exp_id.

Example

http://example.com/getaction/EXP_ID?key=KEY&context=CONTEXT
Parameters

  • exp_id (int) – Experiment ID as specified in the url.

  • key (string) – The key corresponding to the experiment.

  • context (optional) (JSON) – The context to be evaluated.

Returns

A JSON that standard only includes action. When debug is toggled, it returns the context as well. When Advice ID is toggled, it will also return an Advice ID that can be used to set the reward later on.

Raises 400

If the key is not supplied.

Raises 401

If the key or exp_id is invalid.

GET (?i)/setreward/(?P<exp_id>w+)

Update the parameters and set a reward for a given experiment.

For parameters, there are two options (next to the mandatory key and exp_id). The first option is supplying all the information manually, meaning that you supply the following parameters:

  • Context

  • Action

  • Reward

Example

http://example.com/setreward/EXP_ID?key=KEY&context=CONTEXT &action=ACTION&reward=REWARD

When you have toggled the Advice ID in the experiment properties (second option), and have received an Advice ID from the getaction call, you only have to supply the following parameters:

  • Advice ID

  • Reward

Example

http://example.com/setreward/EXP_ID?key=KEY &advice_id=ADVICE_ID&reward=REWARD
Parameters

  • exp_id (int) – Experiment ID as specified in the url.

  • key (string) – The key corresponding to the experiment.

  • context (optional) (JSON) – The context for the current update.

  • action (optional) (JSON) – The action for the current update.

  • advice_id (optional) (string) – The advice_id for the current full update loop.

  • reward (JSON) – The reward for the current update.

Returns

A JSON indicating success.

Raises 400

If key is not supplied.

Raises 401

If the key or exp_id is invalid.

Stats API

The Stats API provides endpoints to retrieve data concerning running experiments. It is possible to retrieve the current state of the stored parameters, retrieve logged data, or retrieve summaries regarding the use of an experiment.

GET (?i)/stats/(?P<exp_id>w+)/currenttheta

Get the current theta.

Example

http://example.com/stats/EXP_ID/currenttheta
Requires

A secure cookie, obtained by logging in.

Parameters

  • exp_id (int) – The experiment ID for the theta that is to be retrieved.

Returns

A JSON of the current theta.

Raises 401

If the experiment does not belong to this user or the exp_id is wrong.

Raises 401

If user is not logged in or if there is no secure cookie available.

GET (?i)/stats/(?P<exp_id>w+)/hourlytheta

Get a dict of all logged thetas.

Example

http://example.com/stats/EXP_ID/hourlytheta?limit=10
Requires

A secure cookie, obtained by logging in.

Parameters

  • exp_id (int) – The experiment ID for the thetas that are to be retrieved.

  • limit (optional) (int) – Set an optional limit to the amount of logs returned.

Returns

A list of JSONs of the hourly logged thetas.

Raises 401

If the experiment does not belong to this user or the exp_id is wrong.

Raises 401

If user is not logged in or if there is no secure cookie available.

GET (?i)/stats/(?P<exp_id>w+)/log

Get all the (manually) logged data.

Example

http://example.com/stats/EXP_ID/log?limit=10
Requires

A secure cookie, obtained by logging in.

Parameters

  • exp_id (int) – The experiment ID for the logs that are to be retrieved.

  • limit (optional) (int) – Set an optional limit to the amount of logs returned.

Returns

A list of JSONs of the logs.

Raises 401

If the experiment does not belong to this user or the exp_id is wrong.

Raises 401

If user is not logged in or if there is no secure cookie available.

GET (?i)/stats/(?P<exp_id>w+)/actionlog

Get all the (automatically) logged get_action data.

Example

http://example.com/stats/EXP_ID/actionlog?limit=10
Requires

A secure cookie, obtained by logging in.

Parameters

  • exp_id (int) – The experiment ID for the logs that are to be retrieved.

  • limit (optional) (int) – Set an optional limit to the amount of logs returned.

Returns

A list of JSONs of the logs.

Raises 401

If the experiment does not belong to this user or the exp_id is wrong.

Raises 401

If user is not logged in or if there is no secure cookie available.

GET (?i)/stats/(?P<exp_id>w+)/rewardlog

Get all the (automatically) logged set_reward data.

Example

http://example.com/stats/EXP_ID/rewardlog?limit=10
Requires

A secure cookie, obtained by logging in.

Parameters

  • exp_id (int) – The experiment ID for the logs that are to be retrieved.

  • limit (optional) (int) – Set an optional limit to the amount of logs returned.

Returns

A list of JSONs of the logs.

Raises 401

If the experiment does not belong to this user or the exp_id is wrong.

Raises 401

If user is not logged in or if there is no secure cookie available.

GET (?i)/stats/(?P<exp_id>w+)/simulationlog

Get all the logged simulation data.

Example

http://example.com/stats/EXP_ID/simulationlog?limit=10
Requires

A secure cookie, obtained by logging in.

Parameters

  • exp_id (int) – The experiment ID for the logs that are to be retrieved.

  • limit (optional) (int) – Set an optional limit to the amount of logs returned.

Returns

A list of JSONs of the logs.

Raises 401

If the experiment does not belong to this user or the exp_id is wrong.

Raises 401

If user is not logged in or if there is no secure cookie available.

GET (?i)/stats/(?P<exp_id>w+)/summary
Get a summary, consisting of:

  • The number of get_action calls

  • The date of the last get_action call

  • The number of set_reward calls

  • The date of the last set_reward call

Example

http://example.com/stats/EXP_ID/summary
Requires

A secure cookie, obtained by logging in.

Parameters

  • exp_id (int) – The experiment ID for the summary that are to be retrieved.

Returns

A JSON object consisting of the summary.

Raises 401

If the experiment does not belong to this user or the exp_id is wrong.

Raises 401

If user is not logged in or if there is no secure cookie available.

Evaluation API

The evaluation API provides the functionality to simulate the running of an experiment. Simulation will execute, in sequence, the getcontext, getaction, getreward, and setreward code as specified when creating a new experiment.

GET (?i)/eval/(?P<exp_id>w+)/simulate

Simulate your experiment based on four scripts, which create a closed feedback loop.

Example

http://example.com/eval/EXP_ID/simulate?N=1000&log_stats=True &verbose=True&seed=10
Requires

A secure cookie, obtained by logging in.

Parameters

  • exp_id (int) – Experiment ID as specified in the url.

  • N (int) – The number of simulation draws.

  • log_stats (bool) – Flag for logging the results in the database (default is False)

  • verbose (bool) – Flag for displaying the results in the returning JSON object (default is True)

  • seed (optional) (int) – Set numpy seed.

Returns

A JSON indicating success when verbose flag is False, and a JSON with all the data when verbose flag is True.

Raises 400

If the experiment does not belong to this user or the exp_id is wrong.

Raises 401

If user is not logged in or if there is no secure cookie available.

Admin API

The admin endpoints provide the functionality to create, alter, and delete experiments.

GET (?i)/exp

Retrieve a list of experiments running on this server

Example

http://example.com/exp
Requires

A secure cookie obtained by logging in.

Returns

A JSON containing exp_id and name pairs.

Raises 401

If user is not logged in or if there is no secure cookie available.

POST (?i)/exp

Create a new experiment

Example
http://example.com/exp
{“name”NAME, “get_context”CODE, “get_action”CODE,

“get_reward” : CODE, “set_reward” : CODE, “advice_id” : True, “hourly_theta” : True, “delta_hours” : DELTA_HOURS, “default_reward” : DEFAULT_REWARD}

Note

The parameters for the POST calls have to be posted in the body as a JSON object.

Requires

A secure cookie obtained by logging in.

Parameters

  • name (string) – Name of the experiment.

  • get_context (optional) (string) – String of python code for get context code.

  • get_action (optional) (string) – String of python code for get action code.

  • get_reward (optional) (string) – String of python code for get reward code.

  • set_reward (optional) (string) – String of python code for set reward code.

  • hourly_theta (bool) – Bool indicating whether the state of Theta should be stored hourly.

  • advice_id (bool) – Bool indicating whether the getadvice and setreward calls should return an advice_id.

  • delta_hours (int) – If advice_id is True, supply this to give the number of hours that an advice_id should be stored (between 0 and 99999).

  • default_reward (dict) – If advice_id is True, supply this to give the default reward for advice_id’s that are over their delta_hours limit.

Returns

A JSON of the form:

{ 
    "id" : The assigned experiment id, 
    "name" : The name of the experiment (checked for duplicates), 
    "error" : (Optional) error message 
    "key" : The key for the experiment 
}
Raises 401

If user is not logged in or if there is no secure cookie available.

GET (?i)/exp/defaults

Get the list with default available experiments.

Example

http://example.com/exp/defaults
Requires

A secure cookie obtained by logging in.

Returns

A JSON with the default experiments.

Raises 401

If user is not logged in or if there is no secure cookie available.

GET (?i)/exp/defaults/(?P<default_id>w+)

Retrieve properties of a default experiment.

Example

http://example.com/exp/defaults/DEFAULT_ID
Requires

A secure cookie obtained by logging in.

Parameters

  • default_id (int) – The ID of the default experiment.

Returns

A JSON containing the experiment properties.

Raises 401

If user is not logged in or if there is no secure cookie available.

GET (?i)/exp/(?P<exp_id>w+)

Retrieve a specific experiment running on this server

Example

http://example.com/exp/EXP_ID
Requires

A secure cookie obtained by logging in.

Parameters

  • exp_id (int) – Experiment ID for the experiment that is to be retrieved.

Returns

A JSON containing all the info for the expriment.

Raises 401

If the experiment does not belong to this user or the exp_id is wrong.

Raises 401

If user is not logged in or if there is no secure cookie available.

DELETE (?i)/exp/(?P<exp_id>w+)

Delete an experiment

Example

http://example.com/exp/EXP_ID
Requires

A secure cookie obtained by logging in.

Parameters

  • exp_id (int) – The ID of the experiment to be deleted.

Returns

A JSON showing the deleted experiment.

Raises 401

If the experiment does not belong to this user or the exp_id is wrong.

Raises 401

If user is not logged in or if there is no secure cookie available.

PUT (?i)/exp/(?P<exp_id>w+)

Edit an experiment

Example

http://example.com/exp/EXP_ID {“name” : NAME, “getcontext” : CODE, “getaction” : CODE,

“getreward” : CODE, “setreward” : CODE, “advice_id” : True, “hourly_theta” : True, “delta_hours” : DELTA_HOURS, “default_reward” : DEFAULT_REWARD}

Note

The parameters for the PUT calls have to be posted in the body as a JSON object.

Requires

A secure cookie obtained by logging in.

Parameters

  • name (string) – Name of the experiment.

  • get_context (optional) (string) – String of python code for get context code.

  • get_action (optional) (string) – String of python code for get action code.

  • get_reward (optional) (string) – String of python code for get reward code.

  • set_reward (optional) (string) – String of python code for set reward code.

  • hourly_theta (bool) – Bool indicating whether the state of Theta should be stored hourly.

  • advice_id (bool) – Bool indicating whether the getAdvice and setReward calls should return an advice_id.

  • delta_hours (int) – If advice_id is True, supply this to give the number of hours that an advice_id should be stored.

  • default_reward (dict) – If advice_id is True, supply this to give the default reward for advice_id’s that are over their delta_hours limit.

Returns

A JSON indicating success.

Raises 401

If the experiment does not belong to this user or the exp_id is wrong.

Raises 401

If user is not logged in or if there is no secure cookie available.

GET (?i)/exp/(?P<exp_id>w+)/resetexperiment

Reset the theta of an experiment.

Example

http://example.com/exp/EXP_ID/resetexperiment?key=KEY &theta_key=THETA_KEY&theta_value=THETA_VALUE
Requires

A secure cookie obtained by logging in.

Parameters

  • exp_id (int) – The experiment ID.

  • key (string) – The key of the experiment.

  • theta_key (optional) (string) – The key for theta used when setting theta in the setReward and getAction code.

  • theta_value (optional) (string) – The value for theta used when setting theta in the setReward and getAction code.

Raises 401

If the theta_key or theta_value does not exist or is not valid.

Raises 401

If the experiment does not belong to this user or the exp_id is wrong.

Raises 401

If user is not logged in or if there is no secure cookie available.

POST (?i)/user

Add a user to StreamingBandit.

Example

http://example.com/user {“username” : USERNAME, “password” : PASSWORD}

Note

The parameters for the POST calls have to be posted in the body as a JSON object.

Parameters

  • username (string) – The preferred username.

  • password (string) – The preferred password.

Returns

JSON indicating success.

Raises 400

If user with username already exists.

Login API

The login API provides secure authentication.

POST (?i)/login

Handler to login and retrieve a secure cookie.

Example

http://example.com/login {“username” : USERNAME, “password” : PASSWORD}

Note

The parameters for the POST calls have to be posted in the body as a JSON object.

Parameters

  • username (string) – Experiment ID as specified in the url.

  • password (string) – The number of simulation draws.

Raises 401

If wrong username or password.

GET (?i)/logout

Handler to logout and clear the set secure cookie.

Example

http://example.com/logout