Date: 2014-11-10
Author: Daniel Waligora
There are two types of methods:
- Cache methods
- Interactive methods
Cache methods are called once per session to retrieve additional information. This information does not require to be sent back to the server or synced again during the session. Example for such data would be an allowed word list for a project. As long as the initial input data does not change, the word list does not change.
Interactive methods are methods that change the state on the client, e.g. querying for new tweets to be labeled by the user.
POST /allowed_word_list
Fetches the allowed word list for a given project. The data is used to validate on the fly the input of the user. E.g.: User assigns a word to a label, only words in the list are allowed to be entered.
| Name | Type | required | Description |
|---|---|---|---|
| project_id | int | Yes |
| Name | Type | required | Description |
|---|---|---|---|
| wordlist | list | Yes | Returns a set of strings. Strings can contain anything, including whitespace, quotes, tabs and UTF-8. |
** Request**
POST /allowed_word_list -d '{"project_id":8}'
** Response**
{
"wordlist": [
"picked",
"random",
"description",
"other"
]
}
POST /labels
Get all unique labels associated with the project.
| Name | Type | required | Description |
|---|---|---|---|
| project_id | int | Yes |
| Name | Type | required | Description |
|---|---|---|---|
| labels | list | yes | set of strings |
** Request**
POST /labels -d '{"project_id":8}'
** Response**
{
"labels": [
"rave",
"rant",
"other"
]
}
POST /word_co_occurence_matrix
In order to show the number of interactions satisfied by word-to-label associations a word co-occurence matrix is needed. The matrix uses a Bag-of-Word representation.
| Name | Type | required | Description |
|---|---|---|---|
| project_id | int | Yes |
| Name | Type | required | Description |
|---|---|---|---|
| word | string | yes | unique word |
| document-ids | list | yes | list of interaction IDs; not necessarily .interaction.id but a miniBrain-created unique ID. Type of the ID: int |
** Request**
POST /word_co_occurence -d '{"project_id":8}'
** Response**
{
"awesome": [
8,
9,
10,
28
],
"awful": [
8,
28,
39,
40
],
"amazing": [
8,
9,
10,
28,
49,
100
]
}
POST /whats_next
Submits the current changes made by the user and simultaneously requests a new command with the necessary data to execute the command on the client. The client knows how to interpret the command but cannot determine what the next step is by itself.
| Name | Type | required | Description |
|---|---|---|---|
| project_id | int | Yes | |
| tweet_labels | list | No | List of tweet-ids with the user-labeled label |
| word_labels | list | No | List of labels with words |
| Name | Type | required | Description |
|---|---|---|---|
| command | string | Yes | one pre-defined command. Dictates what the user interface/user should do. Possible Commands: |
| tweets | list | No | List of tweets needing labeling |
| word_labels | list | No | List of labels with words |
** Request**
POST /whats_next -d '{"project_id":8}'
** Response**
{"command":"annotate_words"}
** Request**
POST /whats_next -d '{"project_id":8}'
** Response**
{
"command": "annotate_tweets",
"tweets": [
{
"id": 8,
"content": "I love you"
},
{
"id": 9,
"content": "I hate you guys"
}
]
}
** Request**
POST /whats_next -d '{"project_id":8}'
** Response**
{
"command": "annotate_tweets",
"tweets": [
{
"id": 8,
"content": "I love you"
},
{
"id": 9,
"content": "I hate you guys"
}
],
"word_labels": {
"rave": [
"amazing",
"awesome",
"best"
],
"rant": [
"terrible",
"horrible",
"dumb"
],
"other": [
"flight",
"blah",
"from"
]
}
}
** Request**
POST /whats_next -d '{"project_id":8,"tweet_labels":{"8":"rave","9":"rave","100":"rant","80":"other"}}'
** Response**
{
"command": "annotate_tweets",
"tweets": [
{
"id": 8,
"content": "I love you"
},
{
"id": 9,
"content": "I hate you guys"
}
],
"word_labels": {
"rave": [
"amazing",
"awesome",
"best"
],
"rant": [
"terrible",
"horrible",
"dumb"
],
"other": [
"flight",
"blah",
"from"
]
}
}
** Request**
POST /whats_next -d '{"project_id":8,"tweet_labels":{"8":"rave","9":"rave","100":"rant","80":"other"},"word_labels":{"rave":["amazing"],"rant":["awful"],"other":["so"]}}'
** Response**
{
"command": "annotate_tweets",
"tweets": [
{
"id": 8,
"content": "I love you"
},
{
"id": 9,
"content": "I hate you guys"
}
]
}
POST /start
Project sessions need to be started and a slot assigned. This is initially done syncroniously. If no error occurs, HTTP code 200 is returned. Otherwise a json object containing an error description is returned.
| Name | Type | required | Description |
|---|---|---|---|
| project_id | int | Yes |
| Name | Type | required | Description |
|---|---|---|---|
| error | string | no | An error message is returned if no slot is available or another problem occured. |
** Request**
POST /start -d '{"project_id":8}'
** Response**
{}
** Request**
POST /start -d '{"project_id":8}'
** Response**
{"error":"no slot available"}
POST /submit_to_brain
Automatically uploads the work done by the user up to this poitn to the brain and schedules a job on the brain. The job itself is run asynchronously but the final job id of the brain can be returned immediately.
| Name | Type | required | Description |
|---|---|---|---|
| project_id | int | Yes |
| Name | Type | required | Description |
|---|---|---|---|
| job_id | string | yes | Job id of the brain job |
** Request**
POST /submit_to_brain -d '{"project_id":8}'
** Response**
{"job_id":"a983f"}
POST /download_work
Download the work of the user by merging the initially uploaded file and the labels provided by the user for the interactions. Removes unlabeled data. Additionally adds the word-to-label associations, independently of the interactions.
| Name | Type | required | Description |
|---|---|---|---|
| project_id | int | Yes |
| Name | Type | required | Description |
|---|---|---|---|
| url | string | yes | S3 filename pointing to a valid interaction file. |
** Request**
POST /download_work -d '{"project_id":8}'
** Response**
{"url":"3983983_labeled_file"}
POST /predictions
Retrieve label predictions and confidences for the currently unlabeled interactions.
| Name | Type | required | Description |
|---|---|---|---|
| project_id | int | Yes |
| Name | Type | required | Description |
|---|---|---|---|
| id | string | yes | interaction ID; not necessarily .interaction.id but a miniBrain-created unique ID |
| label | string | yes | one of the user created labels. Must be included in /labels |
| confidence | double | yes | Real number [0,1] |
| content | string | yes | .interaction.content of the predicted interaction |
** Request**
POST /predictions -d '{"project_id":8}'
** Response**
[
{
"id": "a39db",
"label": "rave",
"confidence": 0.8894,
"content": "Awesome."
},
{
"id": "a38db",
"label": "rant",
"confidence": 0.3894,
"content": "This is shit"
}
]
POST /save
Save the state of the minibrain. If no error occurs, HTTP code 200 is returned.
| Name | Type | required | Description |
|---|---|---|---|
| project_id | int | Yes |
| Name | Type | required | Description |
|---|---|---|---|
| error | string | no | An error message is returned if no slot is available or another problem occured. |
** Request**
POST /save -d '{"project_id":8}'
** Response**
{}
**Request **
POST /save -d '{"project_id":8}'
** Response **
{"error":"write permission denied"}