apiary.apib

FORMAT: 1A
# CrowdComputer (CroCo) API
This is the ***Crowdcomputer API***. This API provides and easy way to crowdsourcer your application.
Building the future of Crowdsourcing API: crowdsourcing as a service

[Crowdcomputer](www.crowdcomputer.org) is created at the University of Trento, Italy by [Stefano](www.stefanotranquillini.me) and [Pavel](www.kucherbaev.com).

#Authorization
The api are protected by a  *token* authentication. The platform accept two types of tokens that are meant to be used in two scnearios. The *single-requester-app* that should be used when the requester is the same person as the owner of the app, and *multiple-requesters-app* that is for applications that post tasks on behalf of other requesters.

##Single-requester-app
The token identifies the *application*.
Example:
```
    e4f4fb816c42b3ff34cc8eb46654a75478fb74c9
```

When a task is created with this token the requester becomes the owner of the application. 
There's no need to ask users to login (except for workers, they must be logged in in the platform)

##Multiple-requesters-app
In this case the app can post task on behalf or other users.  Users (requesters) have to be logged in in the system (see the rest of this paragraph for clarification).

The token identifies the *user* and the *application*. It is composed of two parts, seprated by a `/`
- apptoken
- usertoken

```
    e4f4fb816c42b3ff34cc8eb46654a75478fb74c9/38ce17d422f52a3e3eb88a71c5a547a3e156973c
```


###App token, requester login and authorization
To be able to use the API you have to create an application (*URL NOT AVAILABLE YET*), which will automatically create an application token for you.
The application token identifies your app, thus all the request made with that token will identifiy your application, for example: the list of task of a user is only the list of tasks of that user created with that application.

The user token is given back to you app when a user logs in. To login a user, call this webpage (`../login?callback=<your callback url>`). Once the user logs in the page will redirect to the `callback` page you specified when u created your application.
*Be sure that the `callback` that you specified when you created the app, and the one that you use as parameter of `/login` are the same.*

NB: The user has to grant access to the app before the app can act on his behalf. This will be managed by our login pages.

User token will be appended to the url.

Example:

- `../login?callback=http://test.com`
- users logs in
- app is granted by the user
- systems redirect to `http://test.com?token=38ce17d422f52a3e3eb88a71c5a547a3e156973c`

*this is used to log in the requesters*

#API List

#Group Task
## Task [/task/]

### Retrive the list of task [GET]
This method returns the list of tasks that are created by that specific application

+ Request (text/plain)
    + Headers

            Authorization: Token X/Y
    + Body
    
            {}

+ Response 201 (application/json)

    + Body

            [
                {
                    "owner": "stefano", 
                    "id": 1, 
                    "title": "Task 1", 
                    "description": "Desc Task 1", 
                    "date_created": "2014-05-01T14:34:21.701", 
                    "date_deadline": "2014-05-05T12:00:00Z", 
                    "status": "ST", 
                    "uuid": "52ed354a896a4ca38edd3946d58d7b06", 
                    "page_url": "http://www.crowdcomputer.com/testpage.html",
                    "reward" : 1.0
                }, 
                {
                    "owner": "stefano", 
                    "id": 3, 
                    "title": "Task 2",
                    "description": "task 2", 
                    "date_created": "2014-05-01T20:08:40.446", 
                    "date_deadline": "2014-05-05T12:00:00Z", 
                    "status": "ST", 
                    "uuid": "df78d71867de49029163aca10bf534de", 
                    "page_url": "http://www.crowdcomputer.com/testpage.html",
                    "reward" : 1.0
                }
            ]

### Create a task [POST]
This creates a task. ***Page URL*** must be an external webpage prepared following the instructions (NOT YET ONLINE). ***reward*** has to be specified in EUR.

+ Request JSON message
    + Headers

            Authorization:Token X/Y

    + Body
        
            {
                "title" : "Task title",
                "description" : "Task Description",
                "date_deadline" : "2014-05-05T12:00:00Z",
                "page_url":"http://www.crowdcomputer.org/testme.html",
                "reward": 0.5
            }

+ Response 201 (application/json)

    + Body

            {
                "owner": "stefano", 
                "id": 4, 
                "title": "Task title",
                "description": "Task Description", 
                "date_created": "2014-05-02T21:08:40.446", 
                "date_deadline": "2014-05-05T12:00:00Z", 
                "status": "ST", 
                "uuid": "feed552cd3174a49a4d1324e2cc53de8", 
                "page_url": "http://www.crowdcomputer.com/testme.html",
                "reward" : 0.5
            }

## Task Detail [/task/{id}/]

+ Parameters
    
    + id (required, number) ... The id of the task.

### Get a task [GET]
This updates a task.

+ Request JSON message
    + Headers

            Authorization:Token X/Y

    + Body
        
+ Response 200 (application/json)

    + Body

            {
                "owner": "stefano", 
                "id": 4, 
                "title": "Task title edited",
                "description": "Task Description", 
                "date_created": "2014-05-02T21:08:40.446", 
                "date_deadline": "2014-05-05T12:00:00Z", 
                "status": "ST", 
                "uuid": "feed552cd3174a49a4d1324e2cc53de8", 
                "page_url": "http://www.crowdcomputer.com/testme.html",
                "reward" : 0.5
            }


### Update a task [PUT]
This updates a task.

+ Request JSON message
    + Headers

            Authorization:Token X/Y

    + Body
        
            {
                "title" : "Task title edited",
                "description" : "Task Description",
                "date_deadline" : "2014-05-05T12:00:00Z",
                "page_url":"http://www.crowdcomputer.org/testme.html",
                "reward": 0.5
            }

+ Response 200 (application/json)

    + Body

            {
                "owner": "stefano", 
                "id": 4, 
                "title": "Task title edited",
                "description": "Task Description", 
                "date_created": "2014-05-02T21:08:40.446", 
                "date_deadline": "2014-05-05T12:00:00Z", 
                "status": "ST", 
                "uuid": "feed552cd3174a49a4d1324e2cc53de8", 
                "page_url": "http://www.crowdcomputer.com/testme.html",
                "reward" : 0.5
            }

### Delete a task [DELETE]
This delete a task.

+ Request (*/*)
    + Headers

            Authorization:Token X/Y

    + Body
            
            {}
        
+ Response 204 


## Start a task [/task/{id}/start/] 
This starts a task

+ Parameters
    
    + id (required, number) ... The id of the task.

### Start [PUT]

+ Request (*/*)
    + Headers

            Authorization:Token X/Y

    + Body
            
            {}
        
+ Response 200 (application/json)

    + Body

            {
                'status':'PR'
            }  

## Stop a task [/task/{id}/stop/] 
This stops a task

+ Parameters
    
    + id (required, number) ... The id of the task.

### Stop [PUT]

+ Request (*/*)
    + Headers

            Authorization:Token X/Y

    + Body
            
            {}
            
+ Response 200 (application/json)

    + Body

            {
                'status':'ST'
            }  


#Group TaskInstance
## Task [/task/{id}/taskinstance]

+ Parameters
    
    + id (required, number) ... The id of the task.

### Retrive the list of taskinstance of a task [GET]
This method returns the list of the task instances of the task identified with `id`

+ Request (text/plain)
    + Headers

            Authorization: Token X/Y
    + Body
            
            {}
+ Response 201 (application/json)

    + Body

            [
               ...
            ]

### Create a taskInstance [POST]
This creates a task instance. ***input*** is the input data for that specific instnace.
This functions checks if the balamnce of the workers is enough to pay this instance.

+ Request JSON message
    + Headers

            Authorization:Token X/Y

    + Body
        
            {
                "input" : {} //optional, must be a json
            }

+ Response 201 (application/json)

    + Body

            {
                ...
            }

## TaskInstance Detail [/task/{id}/taskinstance/{id_instance}/]

+ Parameters
    
    + id (required, number) ... The id of the task.
    + id_instance (required, number) ... The id of the task instance.

### Get a task instnace [GET]
This returns the details of  a task instance.

+ Request JSON message
    + Headers

            Authorization:Token X/Y

    + Body
        
+ Response 200 (application/json)

    + Body

            {
            ...
            }

### Update a task instance [PUT]
This updates a task instance.

+ Request JSON message
    + Headers

            Authorization:Token X/Y

    + Body
        
            {
              ...
            }

+ Response 200 (application/json)

    + Body

            {
               ...
            }

### Delete a task instance [DELETE]
This delete a task.

+ Request (*/*)
    + Headers

            Authorization:Token X/Y

    + Body
            
            {}
        
+ Response 204 


## Start a task instance [/task/{id}/taskinstance/{id_instance}/start/] 
This starts a task

+ Parameters
    
    + id (required, number) ... The id of the task.
    + id_instance (required, number) ... The id of the task instance.


### Start [POST]

+ Request (*/*)
    + Headers

            Authorization:Token X/Y

    + Body
            
            {}
        
+ Response 200 (application/json)

    + Body

            {
                'status':'PR'
            }  

## Stop a task instance [/task/{id}/taskinstance/{id_instance}/stop/] 
This stops a task

+ Parameters
    
    + id (required, number) ... The id of the task.
    + id_instance (required, number) ... The id of the task instance.


### Stop [POST]

+ Request (*/*)
    + Headers

            Authorization:Token X/Y

    + Body
            
            {}
        
+ Response 200 (application/json)

    + Body

            {
                'status':'ST'
            }  

## Assign a task instance to a worker [/task/{id}/taskinstance/{id_instance}/assign/] 
This assign the task instance to a worker

+ Parameters
    
    + id (required, number) ... The id of the task.
    + id_instance (required, number) ... The id of the task instance.


### Assign [POST]

+ Request (*/*)
    + Headers

            Authorization:Token X/Y

    + Body
    
            {
                'worker': 1 //id of the worker

            }
        
+ Response 200 (application/json)

    + Body

            {
               ...
            }  

## Execute a task instance, thus update the task instance metadata [/task/{id}/taskinstance/{id_instance}/execute/] 
This updates the task instance metadata.

+ Parameters
    
    + id (required, number) ... The id of the task.
    + id_instance (required, number) ... The id of the task instance.


### Execute [POST]

+ Request (*/*)
    + Headers

            Authorization:Token X/Y

    + Body

            {
                'result': {} //a json object

            }
        
+ Response 200 (application/json)

    + Body

            {
               ...
            }

## Give the reward to an worker of a task instance [/task/{id}/taskinstance/{id_instance}/reward_give/]
This give the reward to the worker of the instance taking the money from the requester account.

+ Parameters

    + id (required, number) ... The id of the task.
    + id_instance (required, number) ... The id of the task instance.

### Execute [POST]

+ Request (*/*)
    + Headers

            Authorization:Token X/Y

    + Body

            {}

+ Response 200 (application/json)

    + Body

            {
               'details':  'Reward of ... given'
            }

## Reject the reward to an worker of a task instance [/task/{id}/taskinstance/{id_instance}/reward_reject/]
This rejects the reward for a worker.

+ Parameters

    + id (required, number) ... The id of the task.
    + id_instance (required, number) ... The id of the task instance.

### Execute [POST]

+ Request (*/*)
    + Headers

            Authorization:Token X/Y

    + Body

            {}

+ Response 200 (application/json)

    + Body

            {
               'details':  'Reward of ... rejected'
            }

## Set the quality of a task instance [/task/{id}/taskinstance/{id_instance}/quality_set/]
This sets the quality of a task instance

+ Parameters

    + id (required, number) ... The id of the task.
    + id_instance (required, number) ... The id of the task instance.

### Execute [POST]

+ Request (*/*)
    + Headers

            Authorization:Token X/Y

    + Body

            {
                'value': 55 //number between 0 and 100
            }

+ Response 200 (application/json)

    + Body

            {
               'details':  'Quality set'
            }

## Get the quality of a task instance [/task/{id}/taskinstance/{id_instance}/qualit_get/]
This gets the quality of a task instance

+ Parameters

    + id (required, number) ... The id of the task.
    + id_instance (required, number) ... The id of the task instance.

### Execute [GET]

+ Request (*/*)
    + Headers

            Authorization:Token X/Y

    + Body

            {
            }

+ Response 200 (application/json)

    + Body

            {
               'value':  55
            }