BanditAPI

Bandit test support api.

Logics are from Bandit Algorithms for Website Optimization

Supported Models

• epsilon-greedy
• softmax
• ucb1

Runs API

1. $ npm install -g bandit-api
2. write your config (default is here)
3. $ bandit-cmd -c /path/to/config or runs as default $ bandit-cmd

Command-line options

$ bandit-cmd --help

  Usage: bandit-cmd [options]

  Options:

    -h, --help           output usage information
    -V, --version        output the version number
    -c, --config <path>  set config path

Documents

Endpoint base url

yourhost:13579/ (13579 is default port)

Request formats

• All request should have Content-type: application/json header
• All request parameters must embed on request body

Response formats

• All response has 200(success) or 400(fail) status
• All response has json body

Supported APIs

/create (POST)

Creates new bandit model.

request parameters

parameter	type	required	description
algorithm	string	true	algorithm name epsilon_greedy, softmax or ucb_1
arm_names	string[]	either arm_names or num_arms required	name of arm(s)
num_arms	integer	either arm_names or num_arms required	arm counts
settings	object	true	algorithm depended settings
settings.epsilon	number	required in epsilon_greedy	value of epsilon. (0<=epsilon<=1)
settings.tau	number	required in softmax	tau parameter value(annealing templature) (0<=tau)

response

Response body contains created model. Your application must coordinate arm_ids and your options.

{
  "algorithm": "EpsilonGreedy",
  "model_id": "558d81548bacc82746f2ca6a",
  "arms": [
    {
      "name": "alice",
      "arm_id": "558d81548bacc82746f2ca6f",
      "value": 0
    },
    {
      "name": "bob",
      "arm_id": "558d81548bacc82746f2ca6e",
      "value": 0
    }
  ],
  "settings": {
    "epsilon": 0.4
  }
}

example

$ curl -H "Content-type: application/json" -X POST -d '{"algorithm": "epsilon_greedy","arm_names":["alice", "bob"],"settings":{"epsilon":0.8}}' localhost:13579/create

$ curl -H "Content-type: application/json" -X POST -d '{"algorithm": "epsilon_greedy","num_arms":5,"settings":{"epsilon":0.8}}' localhost:13579/create

/status (GET)

Get status of current bandit model.

request parameters

parameter	type	required	description
model_id	string	true	model's id returned from create api

response

It is same format of create's response.

{
  "model_id": "558d81548bacc82746f2ca6a",
  "algorithm": "EpsilonGreedy",
  "arms": [
    {
      "name": "alice",
      "arm_id": "558d81548bacc82746f2ca6f",
      "value": 0
    },
    {
      "name": "bob",
      "arm_id": "558d81548bacc82746f2ca6e",
      "value": 1.388
    }
  ],
  "settings": {
    "epsilon": 0.4
  }
}

example

$ curl -H "Content-type: application/json" -X GET -d '{"model_id":"558bae466b1296aa733176f6"}' localhost:13579/status

/get (GET)

Get arm's id that your application should test.

request parameters

parameter	type	required	description
model_id	string	true	model's id returned from create api

response

{
  "name": "alice",
  "arm_id": "558d81548bacc82746f2ca6f"
}

example

$ curl -H "Content-type: application/json" -X GET -d '{"model_id":"558bae466b1296aa733176f6"}' localhost:13579/get

/insert (POST)

Insert a test result to your bandit model.

request parameters

parameter	type	required	description
model_id	string	true	model's id returned from create api
arm_id	string	true	arm's id returned from get api
reward	number	true	testing result value. ucb_1 has a limitation 0 <= reward <= 1

response

Empty response.

{}

example

$ curl -H "Content-type: application/json" -X POST -d '{"model_id":"558bae466b1296aa733176f6", "arm_id":"558bae466b1296aa733176f9","reward":3}' localhost:13579/insert

/delete (DELETE)

Delete your bandit test model.

request parameters

parameter	type	required	description
model_id	string	true	model's id returned from create api

response

Empty response.

{}

example

$ curl -H "Content-type: application/json" -X DELETE -d '{"model_id":"558bae466b1296aa733176f6"}' localhost:13579/delete

TODOs

• Add new algorithm: exp3
• Add new api for arm maneuvering (add/delete/add name/update name)
• Add request result field to response object