REST API

This page documents the REST API that lies at the heart of Myna.

We have developed several client libraries for the API that simplify integration with popular programming languages - we recommend using these libraries wherever possible.

If we haven’t produced a client library for your programming language of choice, or if you just want to get your hands dirty, read on to find out more.

Overview

All API actions are performed by accessing URLs of the form

http://api.mynaweb.com/v1/action/subaction

For example, the following URL will get a suggestion from an experiment:

http://api.mynaweb.com/v1/experiment/
         45923780-80ed-47c6-aa46-15e2ae7a0e8c/suggest

UUIDs

Experiments in Myna are identified by universally unique identifiers (UUIDs). An example UUID is 45923780-80ed-47c6-aa46-15e2ae7a0e8c. The UUIDs of your experiments are shown on your Dashboard. You will need to know these UUIDs to use the API.

Request formats

Myna accepts both GET and POST requests, over both SSL (HTTPS) and unencrypted connections. You must use SSL encrypted requests for all calls that require authentication. For other calls use whichever is more convenient. In particular, cross-domain requests from a web browser must be GET requests and to avoid security warnings should match the protocol (HTTP or HTTPS) used by the page the browser is displaying.

GET and POST requests have different content types. POST requests expect a JSON body, whereas GET requests expect URL-encoded request parameters. For example, the reward action expects two parameters, called token and amount. If you were to send a GET request, you’d use a URL like:

http://api.mynaweb.com/v1/experiment/
         45923780-80ed-47c6-aa46-15e2ae7a0e8c/reward?
             token=871ec6f8-bea7-4a51-ba48-33bdfea9feb2&amount=1.0

If sending a POST request, the body of the request would look like:

{
  "token": "871ec6f8-bea7-4a51-ba48-33bdfea9feb2",
  "amount": 1.0
}

All API actions include examples to illustrate their use.

Response formats

The API currently supports responses in JSON format. To indicate you accept JSON, you should set the the Accept header of the request to application/json.

The suggest and reward actions are special in also providing JSONP responses. If you require JSONP you should set the Accept header to application/javascript.

JSONP results have exactly the same format as JSON results, except they are wrapped in a function application of the form mynaCallback(<JSON response>). The name of the function invoked is set to the value of the callback parameter in the request, if one is present. Otherwise the default value of mynaCallback is used.

Authentication

Many API actions require you to authenticate. Myna uses basic access authentication. Your user name is the email address you use to login to Myna.

Basic access authentication sends passwords in clear text. To ensure your password is not compromised you should only make SSL encrypted (HTTPS) calls to actions that require authentication.

Error handling

Should an API action encounter an error, the response will have an HTTP code in the range 400-499 if the client is in error, or 500-599 if the server had an error.

The response object has the following name/value pairs:

  • typename: problem
  • subtype: Integer A numeric code identifying the HTTP response code associated with error
  • messages: Array An array of JSON objects giving more information about the problem

Example

$ curl 'http://api.mynaweb.com/v1/experiment/abcde/suggest'
{
  "typename": "problem",
  "subtype": 400,
  "messages": [
    {
      "typename": "notFound",
      "item": "experiment"
    },
    {
      "typename": "info",
      "message": "Experiment cannot be found"
    }
  ]
}

API actions

Myna’s API deals with manipulating experiments. All these calls start with the URL http://api.mynaweb.com/v1/experiment. API calls that reference a particular experiment use URLs starting with http://api.mynaweb.com/v1/experiment/<uuid>, where <uuid> is the experiment’s UUID as displayed on your Dashboard.

Suggest

The suggest action gets an experiment to suggest a variant to display to a user.

http://api.mynaweb.com/v1/experiment/<uuid>/suggest

The suggest action has no parameters.

On success the response has an HTTP code of 200. The response is an object with the following name/value pairs:

  • typename: suggestion
  • token: String This is a unique identifier that must be sent back to the server when reward is called
  • choice: String The name of the variant the experiment has chosen

Example

$ curl -H 'Accept: application/json' \
       'http://api.mynaweb.com/v1/experiment/45923780-80ed-47c6-aa46-15e2ae7a0e8c/suggest'
{
  "typename": "suggestion",
  "token": "871ec6f8-bea7-4a51-ba48-33bdfea9feb2",
  "choice": "variant2"
}

Reward

The reward action notifies an experiment of the success or failure of a particular suggestion.

http://api.mynaweb.com/v1/experiment/<uuid>/reward

The reward actions has two parameters;

  • token This is the URL encoded token returned by suggest.
  • amount This a number between 0 and 1 inclusive, printed as text in decimal format (e.g. 0, 0.0, 0.5, and so on).

The amount of the reward should indicate how successful the suggestion was. Higher numbers indicate greater success. Myna assumes a reward of 1 if you do not set the amount, and assumes a reward of 0 if you do not call reward explicitly. This means you only need to call reward when you have been successful.

There is currently no explicit time limit on when you can submit a reward following a suggestion, but tokens will eventually expire.

On success the response has an HTTP code of 200. The body of the response is an object with entry with name typename and value ok.

Example using a GET request:

$ curl -H 'Accept: application/json' \
       'http://api.mynaweb.com/v1/experiment/45923780-80ed-47c6-aa46-15e2ae7a0e8c/reward?token=871ec6f8-bea7-4a51-ba48-33bdfea9feb2&amount=1.0'
{"typename": "ok"}

Example using a POST request:

$ curl -d '{"token": "871ec6f8-bea7-4a51-ba48-33bdfea9feb2", "amount": 1.0}' \
       -H 'Accept: application/json' \
       'http://api.mynaweb.com/v1/experiment/45923780-80ed-47c6-aa46-15e2ae7a0e8c/reward'
{"typename": "ok"}

New variant

The new-variant action adds a new variant to an experiment. You must be authenticated to use this action.

https://api.mynaweb.com/v1/experiment/<uuid>/new-variant

The new-variant action has one parameter:

  • variant: String This is the name of the new variant

On success the response has an HTTP code of 200. The body of the response is an object with entry with name typename and value ok.

Example:

$ curl -d '{"variant": "a new variant"}' \
       -H 'Accept: application/json' \
       -H 'Authorization: Basic dGVzdEBleGFtcGxlLmNvbTp0aGVtb3N0c2VjcmV0cGFzc3dvcmQ=' \
       'https://api.mynaweb.com/v1/experiment/45923780-80ed-47c6-aa46-15e2ae7a0e8c/new-variant'
{"typename": "ok"}

Delete variant

The delete-variant action deletes a variant from an experiment. You must be authenticated to use this action.

https://api.mynaweb.com/v1/experiment/<uuid>/delete-variant

The delete-variant action has one parameter:

  • variant: String This is the name of the new variant

On success the response has an HTTP code of 200. The body of the response is an object with entry with name typename and value ok.

Example:

$ curl -d '{"variant": "a new variant"}' \
       -H 'Accept: application/json' \
       -H 'Authorization: Basic dGVzdEBleGFtcGxlLmNvbTp0aGVtb3N0c2VjcmV0cGFzc3dvcmQ=' \
       'https://api.mynaweb.com/v1/experiment/45923780-80ed-47c6-aa46-15e2ae7a0e8c/delete-variant'
{"typename": "ok"}

New experiment

The new action creates a new experiment. You must be authenticated to use this action.

https://api.mynaweb.com/v1/experiment/new

The new action has one parameter:

  • experiment: String This is the name of the new experiment

On success the response has an HTTP code of 200. The body of the response is an object with fields:

  • typename: experiment
  • name: String The name of the experiment
  • uuid: String The UUID of the newly created experiment
  • accountId: String The UUID of the account that created the experiment
  • variants: Array An array of variants, which will be empty

Example:

$ curl -d '{"experiment": "a new experiment"}' \
       -H 'Accept: application/json' \
       -H 'Authorization: Basic dGVzdEBleGFtcGxlLmNvbTp0aGVtb3N0c2VjcmV0cGFzc3dvcmQ=' \
       'https://api.mynaweb.com/v1/experiment/new'
{
  "typename":"experiment",
  "name":"a new experiment",
  "uuid":"69de296e-7fb4-4302-8a41-4e7bf9201a9b",
  "accountId":"eb1fb383-4172-422a-b680-8031cf26a23e",
  "variants":[]
}

Delete experiment

The delete action deletes an experiment. You must be authenticated to use this action.

https://api.mynaweb.com/v1/experiment/<uuid>/delete

The delete action has no parameters.

On success the response has an HTTP code of 200. The body of the response is an object with entry with name typename and value ok.

Example:

$ curl -H 'Accept: application/json' \
       -H 'Authorization: Basic dGVzdEBleGFtcGxlLmNvbTp0aGVtb3N0c2VjcmV0cGFzc3dvcmQ=' \
       'https://api.mynaweb.com/v1/experiment/f8d9eb79-3d8f-41b0-9044-605faddd959c/delete'
{"typename": "ok"}

Reset Experiment

The reset action sets to zero the views and conversions for all the variants in an experiment. You must be authenticated to use this action.

https://api.mynaweb.com/v1/experiment/<uuid>/reset

The reset action has no parameters.

On success the response has an HTTP code of 200. The body of the response is an object with entry with name typename and value ok.

Example:

$ curl -H 'Accept: application/json' \
       -H 'Authorization: Basic dGVzdEBleGFtcGxlLmNvbTp0aGVtb3N0c2VjcmV0cGFzc3dvcmQ=' \
       'https://api.mynaweb.com/v1/experiment/f8d9eb79-3d8f-41b0-9044-605faddd959c/reset'
{"typename": "ok"}

Information

The info action returns summary information about an experiment. You must be authenticated to use this action.

https://api.mynaweb.com/v1/experiment/<uuid>/info

The info action has no parameters.

On success the response has an HTTP code of 200. The body of the response is an object with entry with fields:

  • typename: experiment
  • name: String The name of the experiment
  • uuid: UUID The UUID of the experiment
  • accountId: UUID The UUID of the account that owns this experiment
  • variants: Array An array of variants being tested by this experiment

Each variant has the following fields:

  • typename: variant
  • name: String The name of the variant
  • views: Integer The number of times this variant has been displayed to a user
  • totalReward: Number The number reward this variant has received
  • lowerConfidenceBound: Number The lower limit of a confidence bound on the average reward of this variant
  • upperConfidenceBound: Number The upper limit of a confidence bound on the average reward of this variant

Example:

$ curl -H 'Accept: application/json' \
       -H 'Authorization: Basic dGVzdEBleGFtcGxlLmNvbTp0aGVtb3N0c2VjcmV0cGFzc3dvcmQ=' \
       'https://api.mynaweb.com/v1/experiment/45923780-80ed-47c6-aa46-15e2ae7a0e8c/info'
{
  "typename": "experiment",
   "name": "test",
   "uuid": "45923780-80ed-47c6-aa46-15e2ae7a0e8c",
   "accountId": "eb1fb383-4172-422a-b680-8031cf26a23e",
   "variants": [
     {
       "typename": "variant",
       "name":" variant2",
       "views": 3437,
       "totalReward": 0.5,
       "lowerConfidenceBound": 1.4281856086809537E-7,
       "upperConfidenceBound": 0.0013595354282067297
     },
     {
       "typename": "variant",
       "name": "variant1",
       "views": 36272,
       "totalReward": 80.5,
       "lowerConfidenceBound": 0.001761525073245763,
       "upperConfidenceBound": 0.002759622105151346
     }
   ],
   "created": "2012-07-13T09:00:00.000Z"
}