See https://gist.github.com/arfon/a79777b68dc512c06043 for general API discussion. Also, Arfon has a PDF file outlining our whiteboard design for this API.

Overall vision for the realtime research API:

Refactor Ouroboros to allow support for subject retiring, assignment (including client side), and custom interface commands.
Find an appropriate project for CrowdSynth or engagement-style experiments. Design interface tweaks, messaging, and other interventions into the project.
Subscriber gets access key to experiment on users for a given project. Access has certain limits such as max percentage of users, and time limit (2 months) etc.
Subscriber listens to Kafka stream (using DB replication library) for users coming online.
Subscriber sends a user request command (with possible time demand) to API when an interesting user comes online. API responds with either 200 (OK) or 403 (denied). If OK, these users are available for sending commands.
Control of users via commands is available for the specified time period, subject to certain rate-limit constraints. The subscriber keeps track of what interventions (A/B) have been applied to specific users. Zooniverse API only logs commands sent.

Note: assignment and partitioning happens by users, not subjects, since most of the experiments are designed to study per-user behavior. Attempting to send commands to non-assigned users should result in an error.

Example REST API payloads and responses for realtime commands

General API parameters

These are sent out with every command. Could potentially be batched into a non-RESTful interface to increase performance, but the below documentation abstracts that away. @parrish will work out the details of the authentication method. Specifically, he suggested that the authentication API needs to be refactored and be simpler for this project.

Request

{
  key: "the access key"
  cmd: "which command we're sending"
}

optional parameters:

group_id: (optional) the group/flight that this command is associated with

batched version:

{
  key: "the access key"
  cmds: [
    { command_1 },
    { command_2 },
    ...
  ]
}

Response

{ 
  request_id: "the unique identifier for this request"  
}

batched version:

{ 
  request_ids: [
    request_id_1,
    request_id_2,
    ...
  ]
}

Errors

{
  error_id: SOME_CODE
  error_msg: "What this error is all about"
}

Potential errors:

Authentication error / access key not valid
The user id is not assigned to the subscriber or time allocation expired
The user has gone offline
The rate limit for e-mails or requests are exceeded

NOTE: should properly handle partially completed requests in batched mode.

Specific commands

0a. request permission to grab a user

The subscriber watches the Kafka stream for user login events and determines users of interest for experimentation.

This command requests permission to send command to a user. Access is checked, and if constraints are satisfied, the server responds with 200 OK if the assignment is successful.

Request:

{
  cmd: "request_user"
  user_id: "id of user that we want permission to operate on"
  duration: "**(optional)** amount of time that we want this user for"
}

Default value for duration is up until the end of the access period (the access key expires.)

0b. give up allocation for a user.

We are no longer interested in a user; release our allocation.

{
  cmd: "release_user"
  user_id: "id of user that we want permission to operate on"
}

1. retire a subject when we are certain of its classification

{
  cmd: "retire"
  subject_id: "which subject we're retiring"
}

This command would probably need to be limited to systems that maintain control of the entire Zooniverse project (CrowdSynth or Phil Marshall style.)

Possible extra command: un-retire a subject.

2. assign a subject or group of subjects to a user

This requires some specific implementation on the client API.

Request:

{
  cmd: "assign"
  user_id: "which user we are assigning these subjects to"
  subject_ids: [ list, of, subject, ids, to, assign ] 
  type: "immediate" or "append"
}

Response:

{
  [ list, of, response, ids ]
}

immediate means show these subjects as soon as possible. append means put these subjects on the end of the assign queue. The Ouroboros client API will only show pseudorandomly selected subjects if the assigned queue is empty. This gets around the problem of possibly draining the subject queue and not being sure if assigned or pseudrandom subjects are being shown.

@parrish suggested returning a request id for each user-subject pair, in our discussion 9/12/13.

3. frontend interventions for a user.

These are per-project implemented custom actions that can be sent to a user, such as changing the content of an informational message, applying an interface change to a live session, etc. The actions will probably be pre-defined beforehand when the project is built, and it will support only those actions.

{
  cmd: "frontend"
  action: "type of pre-defined action to be sent to user"
  user_id: "user we are sending this action to"
  # other fields that are custom to the action
}

Possible actions that can be sent:

Messaging

Sends a message to a user, either by dynamically changing a notification section on the task page or through a modal dialog box. Modal dialogs have more intervention power but could be annoying.

{
  action: "message"
  message: "string that we are sending"
  display: "modal" or "inline" # for example
}

Other interventions...

tells the user to take a break and go do something else. Could be useful for getting bad users to leave or whetting someone's appetite before they get tired.
showing a user feedback during initial training
giving encouragement through special interface animations/effects
sending a link to the talk page for a particular subject
give examples of correct classification or results
send user back to tutorial
(not included here) showing users a particularly interesting subject is in the assign command, above

4. Sending e-mail to users

Allow custom messages to be sent to users. Probably should be rate-limited (per-user) on the API end to prevent buggy academic code from spamming in an infinite loop, and observe user notification preferences. Should also be sent with a zooniverse header-footer in the e-mail instead of just plain text.

{
  cmd: "email"  
  user_id: "user we are emailing"
  string: "string to send in e-mail"
}

mizzao/zooniverse_realtime_api.md