diretto Task APIv2 - Draft

diretto Task API

Introduction

Version

v2 - Draft

Author

Benjamin Erb

Description

The Task API represents an external service that enables the handling of certain tasks. In terms of the diretto platform, a task is a request of specific footage. Reporters may take in part in tasks and contribute required documents as submissions. A task is always bound to a location and a time frame. A title and description define the task and optional tags allow to categorize it. Votes help to prioritize different tasks within the community. Tasks can be commented for exchange of ideas. Finally, every user can submit an existing document as footage for the task. The community can then rate the suitability of the submission regarding the task request. Besides the of directed collection of live footage, the Task API can also be used for specialized search queries. In this case, a task represents a search query and all potential results are submissions. This user-driven search is helpful for queries when only users can reason about appropriate hits by analyzing the documents.

Authentication Schemes

Basic Authentication

Base URI

http://task.example.foo/v2

1. Comment

Description

This resource represents a comment. Comments can be added by users to a task in order to discuss the task.

Resource URI

http://task.example.foo/v2/task/{task-id}/comment/{comment-id}

task-id: task ID
comment-id: comment ID

1.1 Create a new comment

Description

Adds a new comment to the task.

URI

http://task.example.foo/v2/task/{task-id}/comments

URI Parameters

{task-id}: task ID

HTTP Method

POST

Resource Formats

application/json

Authentication

required

Request Entities

{
   "content":"blablabla"
}

Responses

201 Created: Comment has been created. The location header contains its URI and thus also the comment id.
400 Bad Request: Invalid comment data.
404 Not Found: Task not found.

Response Entities

n/a

1.2 Get all comments of task

Description

Returns all comments of task.

URI

http://task.example.foo/v2/task/{task-id}/comments

URI Parameters

{task-id}: task ID

HTTP Method

GET

Resource Formats

application/json

Authentication

required

Request Entities

n/a

Responses

200 OK: Comment list in response entity.
404 Not Found: Task not found

Response Entities

{
   "comments":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/task/eafbad70-7972-11e0-a1f0-0800200c9a66/comments"
      },
      "list":[
         {
            "comment":{
               "link":{
                  "rel":"self",
                  "href":"http://task.example.foo/v2/task/eafbad70-7972-11e0-a1f0-0800200c9a66/comment/8e252710-77cf-11e0-a1f0-0800200c9a66"
               },
               "content":"blablabla",
               "creationTime":"2010-07-17T18:54:11.939Z",
               "creator":{
                  "link":{
                     "rel":"self",
                     "href":"http://core/v2/user/123456"
                  }
               },
               "votes":{
                  "link":{
                     "rel":"self",
                     "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/tag/ef7987f2bd22f4a8cf236c83a57c1f6b/votes"
                  },
                  "up":12,
                  "down":2
               }
            }
         }
      ]
   }
}

1.3 Retrieve a single comment

Description

Returns a single comment.

URI

http://task.example.foo/v2/task/{task-id}/comment/{comment-id}

URI Parameters

task-id: task ID
comment-id: comment ID

HTTP Method

GET

Resource Formats

application/json

Authentication

required

Request Entities

n/a

Responses

200 OK
404 Not Found

Response Entities

{
   "comment":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/task/eafbad70-7972-11e0-a1f0-0800200c9a66/comment/8e252710-77cf-11e0-a1f0-0800200c9a66"
      },
      "content":"blablabla",
      "creationTime":"2010-07-17T18:54:11.939Z",
      "creator":{
         "link":{
            "rel":"self",
            "href":"http://core/v2/user/123456"
         }
      },
      "votes":{
         "link":{
            "rel":"self",
            "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/tag/ef7987f2bd22f4a8cf236c83a57c1f6b/votes"
         },
         "up":12,
         "down":2
      }
   }
}

2. Index

Description

This entry resource provides information about the service instance.

Resource URI

http://task.example.foo/v2

2.1 Get service instance data

Description

Returns a static information about the deployed Task service instance.

URI

http://task.example.foo/v2

URI Parameters

n/a

HTTP Method

GET

Resource Formats

application/json

Authentication

not required

Request Entities

n/a

Responses

200 OK: Service instance data in response entity

Response Entities

{
   "api":{
      "name":"org.diretto.api.external.task",
      "version":"v2"
   },
   "service":{
      "name":"diretto Task Node",
      "version":"0.1.0"
   },
   "deployment":{
      "title":"fubar Task Service",
      "contact":"n/a",
      "website":{
         "link":{
            "rel":"self",
            "href":"http://www.diretto.org"
         }
      }
   },
   "direttoMainServices":{
      "core":{
         "link":{
            "rel":"self",
            "href":"http://core.example.foo/v2"
         }
      }
   },
   "links":[
      {
         "title":"diretto Task API Documentation",
         "link":{
            "rel":"self",
            "href":"http://diretto.github.com/diretto-api-doc/v2/diretto-ext/task.html"
         }
      },
      {
         "title":"Task factory resource",
         "link":{
            "rel":"self",
            "href":"http://task.example.foo/v2/tasks"
         }
      },
      {
         "title":"Tag factory resource",
         "link":{
            "rel":"self",
            "href":"http://task.example.foo/v2/tags"
         }
      },
      {
         "title":"Query dispatching resource",
         "link":{
            "rel":"self",
            "href":"http://task.example.foo/v2/query"
         }
      }
   ],
   "parameters":{
      "paginationSize":20,
      "batchLimit":50
   }
}

The JSON response contains information about the service identification and version, the actual deployment variables and links to the main service instance.

3. Query

Description

An interface resource for query execution. A query must be dispatched to the server which will return a URI for the query. This URI then contains the results. Results are paginated using cursors. A query resource stores the initial query parameters, not the result set. Thus, queries can be re-executed by using the same URI, although the corresponding results may have changed. Be aware of this fact when applying caching to query results.

   Client                      Task Service

     |                               |
     |                               |
     |      (1) POST Query           |
     |------------------------------>|
     |                               |
     |      (2) 202 + Location       |
     |<------------------------------|
     |                               |
     |                               |
     |      (3) GET Query Resource   |
     |------------------------------>|
     |                               |
     |      (4) 303 + 1st page URI   |
     |<------------------------------|
     |                               |
     |                               |
     |      (5) GET 1st result page  |
     |------------------------------>|
     |                               |
     |      (6) 200 + First page     |
     |<------------------------------|
     |                               |

Note that step 5 and 6 must be repeated for additional result pages. Also, step 1 and 2 can be skipped if an existing query (client already knows query URI) should be re-executed.

Resource URI

http://task.example.foo/v2/query/stored/{query-id}

query-id: query id

3.1 Dispatch a query

Description

Sends a query.

URI

http://task.example.foo/v2/query

URI Parameters

n/a

HTTP Method

POST

Resource Formats

Authentication

required

Request Entities

{
   "query":{
      "time":{
         "start":"2010-06-29T19:15:51.765Z",
         "end":"2010-06-29T19:15:50.000Z"
      },
      "location":{
         "bbox":[
            100.0,
            0.0,
            105.0,
            1.0
         ]
      },
      "tags":[
		"http://task.example.foo/v2/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
      ]
   }
}

A query is built using three parameters. While time frame and spatial bounding box are mandatory, the tag list may be empty. Please not that all parameters are combined conjunctively (using boolean AND), thus each emitted result entry matches all of the parameters.

Responses

202 Accepted: Query accepted, result location in header.
400 Bad Request: Invalid query parameters.

Response Entities

n/a

3.2 Execute a common location-based query

Description

A set of predefined queries for tasks currently valid by time and the user's position. The type affects the order of the tasks emitted as results. You can either provide a bounding box or a concrete position (using lat and lon instead of the four box values).

URI

http://task.example.foo/v2/query/common/{type}?lat1={lat1}&lon1={lon1}&lat2={lat2}&lon2={lon2}

URI Parameters

{type}: type: one of 'newest', 'unattended', 'expiring' or 'popular'
{lat1}: lower bbox latitude
{lon1}: lower bbox longitude
{lat2}: upper bbox latitude
{lon2}: upper bbox longitude

HTTP Method

GET

Resource Formats

Authentication

required

Request Entities

n/a

Responses

202 Accepted: Query accepted, result location in header.
404 Not Found: Invalid coordinates.

Response Entities

n/a

3.3 Forward to query result page

Description

A request to a query URI will always be forwarded to the first page of the result set using the first cursor.

URI

http://task.example.foo/v2/query/stored/{query-id}

URI Parameters

query-id: query id

HTTP Method

GET

Resource Formats

Authentication

required

Request Entities

n/a

Responses

204 No Content: Query returned no results.
303 See Other: Query found, location of query resource in location header.
404 Not Found: Query not found.

Response Entities

n/a

3.4 Get query result page

Description

Returns a paginated result page, identified by the cursor. A result page always contains links to the first page and additionally to the previous and next result page when existing.

URI

http://task.example.foo/v2/query/stored/{query-id}/cursor/{cursor-id}

URI Parameters

query-id: query id
{cursor-id}: cursor id

HTTP Method

GET

Resource Formats

Authentication

required

Request Entities

n/a

Responses

200 OK: Result page in response.
404 Not Found: Query or cursor not found.

Response Entities

{
   "query":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/query/stored/128ecf542a35ac5270a87dc740918404"
      }
   },
   "results":{
      "count":101,
      "page":{
         "link":{
            "rel":"self",
            "href":"http://task.example.foo/v2/query/stored/128ecf542a35ac5270a87dc740918404/cursor/def"
         },
         "list":[
            {
               "task":{
                  "link":{
                     "rel":"self",
                     "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015"
                  }
               }
            }
         ],
         "related":[
            {
               "link":{
                  "rel":"first",
                  "href":"http://task.example.foo/v2/query/stored/128ecf542a35ac5270a87dc740918404/cursor/abc"
               }
            },
            {
               "link":{
                  "rel":"previous",
                  "href":"http://task.example.foo/v2/query/stored/128ecf542a35ac5270a87dc740918404/cursor/abc"
               }
            },
            {
               "link":{
                  "rel":"next",
                  "href":"http://task.example.foo/v2/query/stored/128ecf542a35ac5270a87dc740918404/cursor/ghi"
               }
            }
         ]
      }
   }
}

A query result page containing links to the previous, next and first page. The first page link is always present, the others only when the other pages acutally exist.

4. Submission

Description

This resource represents a submission. A submission basically suggests that a document represents a possible solution to the task.

Resource URI

http://task.example.foo/v2/task/{task-id}/submission/{submission-id}

task-id: task ID
submission-id: submission ID

4.1 Create a new submission

Description

Creates a new submission. A submission is represented by a document, identified by it's URI.

URI

http://task.example.foo/v2/task/{task-id}/submissions

URI Parameters

{task-id}: task ID

HTTP Method

POST

Resource Formats

application/json

Authentication

required

Request Entities

{
   "document":{
      "link":{
         "rel":"self",
         "href":"http://core/v2/document/550e8400-e29b-11d4-a716-446655440000"
      }
   }
}

An example submission of a document.

Responses

201 Created: The submission has been accepted. The location header contains its URI and thus also the submission id.
400 Bad Request: The provided data are incomplete or invalid.
403 Forbidden: The document does not represent a valid submission for this task (spatial location or time origin).
409 Conflict: The document is already a submission for this task.

Response Entities

{
   "error":{
      "reason":"The spatial location of the document is outside the task area."
   }
}

A rejected submission (403) of a document, here due to it's meta data.

4.2 Get all submissions of task

Description

Returns all submissions of task.

URI

http://task.example.foo/v2/task/{task-id}/submissions

URI Parameters

{task-id}: task ID

HTTP Method

GET

Resource Formats

application/json

Authentication

required

Request Entities

n/a

Responses

200 OK: Submission list in response entity.
404 Not Found: Task not found

Response Entities

{
   "submissions":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/task/eafbad70-7972-11e0-a1f0-0800200c9a66/submissions"
      },
      "list":[
         {
            "submission":{
               "link":{
                  "rel":"self",
                  "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000"
               },
               "votes":{
                  "link":{
                     "rel":"self",
                     "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000/votes"
                  },
                  "up":123,
                  "down":42
               },
               "document":{
                  "link":{
                     "rel":"self",
                     "href":"http://core/v2/document/550e8400-e29b-11d4-a716-446655440000"
                  }
               },
               "creationTime":"2010-07-17T18:54:11.939Z",
               "creator":{
                  "link":{
                     "rel":"self",
                     "href":"http://core/v2/user/123456"
                  }
               },
               "tags":{
                  "link":{
                     "rel":"self",
                     "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000/tags"
                  },
                  "list":[
                     {
                        "tag":{
                           "link":{
                              "rel":"self",
                              "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
                           },
                           "baseTag":{
                              "link":{
                                 "rel":"self",
                                 "href":"http://task.example.foo/v2/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
                              }
                           },
                           "value":"mytag",
                           "creationTime":"2010-07-17T18:54:11.939Z",
                           "creator":{
                              "link":{
                                 "rel":"self",
                                 "href":"http://core/v2/user/123456"
                              }
                           },
                           "votes":{
                              "link":{
                                 "rel":"self",
                                 "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000/tag/ef7987f2bd22f4a8cf236c83a57c1f6b/votes"
                              },
                              "up":12,
                              "down":2
                           }
                        }
                     }
                  ]
               }
            }
         }
      ]
   }
}

4.3 Retrieve submission details

Description

Provides detailed information about this submission.

URI

http://task.example.foo/v2/task/{task-id}/submission/{submission-id}

URI Parameters

task-id: task ID
submission-id: submission ID

HTTP Method

GET

Resource Formats

application/json

Authentication

required

Request Entities

n/a

Responses

200 OK: The submission details are available in the response entity.
404 Not Found: Submission not found.

Response Entities

{
   "submission":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000"
      },
      "votes":{
         "link":{
            "rel":"self",
            "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000/votes"
         },
         "up":123,
         "down":42
      },
      "document":{
         "link":{
            "rel":"self",
            "href":"http://core/v2/document/550e8400-e29b-11d4-a716-446655440000"
         }
      },
      "creationTime":"2010-07-17T18:54:11.939Z",
      "creator":{
         "link":{
            "rel":"self",
            "href":"http://core/v2/user/123456"
         }
      },
      "tags":{
         "link":{
            "rel":"self",
            "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000/tags"
         },
         "list":[
            {
               "tag":{
                  "link":{
                     "rel":"self",
                     "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
                  },
                  "baseTag":{
                     "link":{
                        "rel":"self",
                        "href":"http://task.example.foo/v2/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
                     }
                  },
                  "value":"mytag",
                  "creationTime":"2010-07-17T18:54:11.939Z",
                  "creator":{
                     "link":{
                        "rel":"self",
                        "href":"http://core/v2/user/123456"
                     }
                  },
                  "votes":{
                     "link":{
                        "rel":"self",
                        "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000/tag/ef7987f2bd22f4a8cf236c83a57c1f6b/votes"
                     },
                     "up":12,
                     "down":2
                  }
               }
            }
         ]
      }
   }
}

5. Tag

Description

This resource represents a tag. Users can append tags on various resources. The tag URI path is appended to the original URI. The following resources of the Task API can be tagged: Task and Submission

   Client                      Task Service

     |                               |
     |                               |
     |   (1) POST Tag                |
     |------------------------------>|
     |                               |
     |   (2) 201/202 + Location      |
     |<------------------------------|
     |                               |
     |                               |
     |   (3) POST Tag to Resource    |
     |------------------------------>|
     |                               |
     |   (4) 201/202 + Location      |
     |<------------------------------|
     |                               |
     |                               |

Steps 1+2 create a tag, steps 3+4 append the tag to a resource.

Resource URI

http://task.example.foo/v2/tag/{tag-id}

tag-id: tag ID

5.1 Append a tag to a resource

Description

Appends a new tag to the resource.

URI

http://task.example.foo/v2/{resource}/tags

URI Parameters

{resource}: resource

HTTP Method

POST

Resource Formats

application/json

Authentication

required

Request Entities

{
   "baseTag":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
      }
   }
}

Responses

201 Created: Tag has been appended. The location header contains its URI and thus also the tag id.
202 Accepted: Tag already exists, but accepted.
400 Bad Request: Invalid tag data (i.e. ID mismatch).
404 Not Found: Tag or resource not found.

Response Entities

n/a

5.2 Create a new tag or resolve an existing tag

Description

Create a new tag that can be appended to resource thereafter. This API call can also be used to retrieve the internal ID of an existing tag.

URI

http://task.example.foo/v2/tags

URI Parameters

n/a

HTTP Method

POST

Resource Formats

application/json

Authentication

required

Request Entities

{
   "value":"mytag"
}

Responses

201 Created: Tag has been created. The location header contains its URI and thus also the tag id.
202 Accepted: Tag already exists, but accepted.
400 Bad Request: Invalid tag data (i.e. length).

Response Entities

{
   "baseTag":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
      }
   }
}

5.3 Create or resolve multiple tags (batch request)

Description

Takes a list of textual tags and either creates or resolves each of them. For every single tag, either the base tag URI or an error message is returned.

URI

http://task.example.foo/v2/tags/multiple

URI Parameters

n/a

HTTP Method

POST

Resource Formats

application/json

Authentication

required

Request Entities

{
   "values":["t","mytag"]
}

Responses

200 OK: List of tags in response.
400 Bad Request: Invalid request (i.e. empty list)

Response Entities

{
   "results":{
      "mytag":{
         "baseTag":{
            "link":{
               "rel":"self",
               "href":"http://task.example.foo/v2/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
            }
         }
      },
      "t":{
         "error":{
            "reason":"Invalid tag length"
         }
      }
   }
}

5.4 Retrieve all tags of a resource

Description

Returns a single tag entry.

URI

http://task.example.foo/v2/{resource}/tags

URI Parameters

{resource}: resource

HTTP Method

GET

Resource Formats

application/json

Authentication

required

Request Entities

n/a

Responses

200 OK
404 Not Found: Resource not found.

Response Entities

{
   "tags":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/resource/tags"
      },
      "list":[
         {
            "tag":{
               "link":{
                  "rel":"self",
                  "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
               },
               "baseTag":{
                  "link":{
                     "rel":"self",
                     "href":"http://task.example.foo/v2/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
                  }
               },
               "value":"mytag",
               "creationTime":"2010-07-17T18:54:11.939Z",
               "creator":{
                  "link":{
                     "rel":"self",
                     "href":"http://core/v2/user/123456"
                  }
               },
               "votes":{
                  "link":{
                     "rel":"self",
                     "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/tag/ef7987f2bd22f4a8cf236c83a57c1f6b/votes"
                  },
                  "up":12,
                  "down":2
               }
            }
         }
      ]
   }
}

5.5 Retrieve a single tag of a resource

Description

Returns a single tag entry that has been appended to a resource.

URI

http://task.example.foo/v2/{resource}/tag/{tag-id}

URI Parameters

{resource}: resource identifier
{tag-id}: tag ID

HTTP Method

GET

Resource Formats

application/json

Authentication

required

Request Entities

n/a

Responses

200 OK
404 Not Found: Resource not found.

Response Entities

{
   "tag":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
      },
      "baseTag" : {
	      "link":{
	         "rel":"self",
	         "href":"http://task.example.foo/v2/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
	      }
      }, 
      "value":"mytag",
      "creationTime":"2010-07-17T18:54:11.939Z",
      "creator":{
         "link":{
            "rel":"self",
            "href":"http://core/v2/user/123456"
         }
      },
      "votes":{
         "link":{
            "rel":"self",
            "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/tag/ef7987f2bd22f4a8cf236c83a57c1f6b/votes"
         },
         "up":12,
         "down":2
      }
   }
}

Note that the creation time denotes the time this tag has been appended to the resource for the first time.

5.6 Retrieve a tag

Description

Returns a tag entry.

URI

http://task.example.foo/v2/tag/{tag-id}

URI Parameters

tag-id: tag ID

HTTP Method

GET

Resource Formats

application/json

Authentication

required

Request Entities

n/a

Responses

200 OK
404 Not Found: Tag not found.

Response Entities

{
   "baseTag":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
      },
      "value":"mytag",
      "creationTime":"2010-07-17T18:54:11.939Z",
      "creator":{
         "link":{
            "rel":"self",
            "href":"http://core/v2/user/123456"
         }
      }
   }
}

Note that the creation time denotes the initial usage of this time.

6. Task

Description

This resource represents a task.

Resource URI

http://task.example.foo/v2/task/{task-id}

task-id: task ID

6.1 Create a new task

Description

Creates a new task.

URI

http://task.example.foo/v2/tasks

URI Parameters

n/a

HTTP Method

POST

Resource Formats

application/json

Authentication

required

Request Entities

{
   "constraints":{
      "time":{
         "start":"2010-06-29T16:00:51.765Z",
         "end":"2010-06-29T19:15:50.000Z"
      },
      "location":{
         "bbox": [100.0, 0.0, 105.0, 1.0]
      }
   },
   "title":"foo bar",
   "description":"foo bar asd lorem"
}

Responses

201 Created: Task has been created. The location header contains its URI and thus also the task id.
400 Bad Request: The provided data are incomplete or invalid.

Response Entities

n/a

6.2 Fetch meta data of multiple tasks (batch request)

Description

Fetches a set of task snapshots.

URI

http://task.example.foo/v2/tasks/metadata

URI Parameters

n/a

HTTP Method

POST

Resource Formats

application/json

Authentication

required

Request Entities

{
   "tasks":[
      "http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015",
      "http://task.example.foo/v2/task/2671f383-a28c-bla"
   ]
}

Responses

200 OK: Results in response body. Note that tasks may still have raised errors (i.e. when not found).
400 Bad Request: Invalid query or too many items requested.

Response Entities

{
   "results":{
      "http://task.example.foo/v2/task/2671f383-a28c-bla":{
         "error":{
            "reason":"Not found"
         }
      },
      "http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015":{
         "task":{
            "link":{
               "rel":"self",
               "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015"
            },
            "constraints":{
               "time":{
                  "start":"2010-06-29T16:00:51.765Z",
                  "end":"2010-06-29T19:15:50.000Z"
               },
               "location":{
                  "bbox":[
                     100.0,
                     0.0,
                     105.0,
                     1.0
                  ]
               }
            },
            "title":"foo bar",
            "description":"foo bar asd lorem",
            "creationTime":"2010-07-17T18:54:11.939Z",
            "creator":{
               "link":{
                  "rel":"self",
                  "href":"http://core/v2/user/123456"
               }
            },
            "votes":{
               "link":{
                  "rel":"self",
                  "href":"http://task.example.foo/v2/resource/votes"
               },
               "up":123,
               "down":42
            }
         },
         "submissions":{
            "link":{
               "rel":"self",
               "href":"http://task.example.foo/v2/task/eafbad70-7972-11e0-a1f0-0800200c9a66/submissions"
            }
         },
         "comments":{
            "link":{
               "rel":"self",
               "href":"http://task.example.foo/v2/task/eafbad70-7972-11e0-a1f0-0800200c9a66/comments"
            }
         },
         "tags":{
            "link":{
               "rel":"self",
               "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/tags"
            }
         }
      }
   }
}

6.3 Fetch multiple task snapshots (batch request)

Description

Fetches a set of task snapshots.

URI

http://task.example.foo/v2/tasks/snapshots

URI Parameters

n/a

HTTP Method

POST

Resource Formats

application/json

Authentication

required

Request Entities

{
   "tasks":[
      "http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015",
      "http://task.example.foo/v2/task/2671f383-a28c-bla"
   ]
}

Responses

200 OK: Results in response body. Note that tasks may still have raised errors (i.e. when not found).
400 Bad Request: Invalid query or too many items requested.

Response Entities

{
   "results":{
      "http://task.example.foo/v2/task/2671f383-a28c-bla":{
         "error":{
            "reason":"Not found"
         }
      },
      "http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015":{
         "task":{
            "link":{
               "rel":"self",
               "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015"
            },
            "constraints":{
               "time":{
                  "start":"2010-06-29T16:00:51.765Z",
                  "end":"2010-06-29T19:15:50.000Z"
               },
               "location":{
                  "bbox":[
                     100.0,
                     0.0,
                     105.0,
                     1.0
                  ]
               }
            },
            "title":"foo bar",
            "description":"foo bar asd lorem",
            "creationTime":"2010-07-17T18:54:11.939Z",
            "creator":{
               "link":{
                  "rel":"self",
                  "href":"http://core/v2/user/123456"
               }
            },
			"votes":{
			     "link":{
			            "rel":"self",
			            "href":"http://task.example.foo/v2/resource/votes"
			         },
			      "up":123,
			      "down":42
			   }      
		   }            
         },
         "submissions":{
            "link":{
               "rel":"self",
               "href":"http://task.example.foo/v2/task/eafbad70-7972-11e0-a1f0-0800200c9a66/submissions"
            },
            "list":[
               {
                  "submission":{
                     "link":{
                        "rel":"self",
                        "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000"
                     },
                     "votes":{
                        "link":{
                           "rel":"self",
                           "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000/votes"
                        },
                        "up":123,
                        "down":42
                     },
                     "document":{
                        "link":{
                           "rel":"self",
                           "href":"http://core/v2/document/550e8400-e29b-11d4-a716-446655440000"
                        }
                     },
                     "creationTime":"2010-07-17T18:54:11.939Z",
                     "creator":{
                        "link":{
                           "rel":"self",
                           "href":"http://core/v2/user/123456"
                        }
                     },
                     "tags":{
                        "link":{
                           "rel":"self",
                           "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000/tags"
                        },
                        "list":[
                           {
                              "tag":{
                                 "link":{
                                    "rel":"self",
                                    "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
                                 },
                                 "baseTag":{
                                    "link":{
                                       "rel":"self",
                                       "href":"http://task.example.foo/v2/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
                                    }
                                 },
                                 "value":"mytag",
                                 "creationTime":"2010-07-17T18:54:11.939Z",
                                 "creator":{
                                    "link":{
                                       "rel":"self",
                                       "href":"http://core/v2/user/123456"
                                    }
                                 },
                                 "votes":{
                                    "link":{
                                       "rel":"self",
                                       "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000/tag/ef7987f2bd22f4a8cf236c83a57c1f6b/votes"
                                    },
                                    "up":12,
                                    "down":2
                                 }
                              }
                           }
                        ]
                     }
                  }
               }
            ]
         },
         "comments":{
            "link":{
               "rel":"self",
               "href":"http://task.example.foo/v2/task/eafbad70-7972-11e0-a1f0-0800200c9a66/comments"
            },
            "list":[
               {
                  "comment":{
                     "link":{
                        "rel":"self",
                        "href":"http://task.example.foo/v2/task/eafbad70-7972-11e0-a1f0-0800200c9a66/comment/8e252710-77cf-11e0-a1f0-0800200c9a66"
                     },
                     "content":"blablabla",
                     "creationTime":"2010-07-17T18:54:11.939Z",
                     "creator":{
                        "link":{
                           "rel":"self",
                           "href":"http://core/v2/user/123456"
                        }
                     },
                     "votes":{
                        "link":{
                           "rel":"self",
                           "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/tag/ef7987f2bd22f4a8cf236c83a57c1f6b/votes"
                        },
                        "up":12,
                        "down":2
                     }
                  }
               }
            ]
         },
         "tags":{
            "link":{
               "rel":"self",
               "href":"http://task.example.foo/v2/resource/tags"
            },
            "list":[
               {
                  "tag":{
                     "link":{
                        "rel":"self",
                        "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
                     },
                     "baseTag":{
                        "link":{
                           "rel":"self",
                           "href":"http://task.example.foo/v2/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
                        }
                     },
                     "value":"mytag",
                     "creationTime":"2010-07-17T18:54:11.939Z",
                     "creator":{
                        "link":{
                           "rel":"self",
                           "href":"http://core/v2/user/123456"
                        }
                     },
                     "votes":{
                        "link":{
                           "rel":"self",
                           "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/tag/ef7987f2bd22f4a8cf236c83a57c1f6b/votes"
                        },
                        "up":12,
                        "down":2
                     }
                  }
               }
            ]
         }
      }
   }
}

6.4 List all existing tasks

Description

Forwards to a paginated list of all tasks available.

URI

http://task.example.foo/v2/tasks

URI Parameters

n/a

HTTP Method

GET

Resource Formats

Authentication

required

Request Entities

n/a

Responses

204 No Content: No task available yet
303 See Other: Location header contains link to first page of tasks

Response Entities

6.5 List page of tasks (cursored)

Description

A page of tasks as part of a complete list of all tasks. Each page is identified by a cursor task, which represents the first task to be included into the page. Pages and tasks of a page are sorted chronologically by creation date (not by the date constraints of a task). In other words, the cursor task is the first task on the page and all other tasks below are newer (or at least of the same age) than the cursor. If there is a next link, all tasks of the next page are newer (or at least of the same age) that the last entry of the current page. If there is a previous link, the cursor of the current page is newer (or at least of the same age) than the last entry of the previous page. Metaphorically, pages are slices cut from the timeline. When iterating over a page, the items on top are older than the bottom ones.

URI

http://task.example.foo/v2/tasks/cursor/{task id}

URI Parameters

{task id}: Task ID to be used as cursor (first task included in page)

HTTP Method

GET

Resource Formats

application/json

Authentication

required

Request Entities

n/a

Responses

200 OK: Page as response entity
404 Not Found: Non-existing cursor

Response Entities

{
   "page":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/tasks/cursor/2671f383-a28c-44d5-b86b-f7f04bb0a015"
      }
   },
   "list":[
      {
         "task":{
            "link":{
               "rel":"self",
               "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015"
            }
         }
      }
   ],
   "related":[
      {
         "link":{
            "rel":"previous",
            "href":"http://task.example.foo/v2/tasks/cursor/5330edf0-a68d-11e0-8264-0800200c9a66"
         }
      },
      {
         "link":{
            "rel":"next",
            "href":"http://task.example.foo/v2/tasks/cursor/8d45b5ff-c6b8-4ec3-9fd1-96704233be3e"
         }
      }
   ]
}

An example page (containing only one item per page). Please note the related links, which may be available in most cases.

6.6 List tasks created since a specific date

Description

Forwards to a paginated list of all tasks created since the date that has been passed as parameter. The result list is inclusive, thus an exact match will also be included. The date parameter must be a RFC 3339 compliant value, using Zulu time. The list forwared to will provide all results ordered by creation time. The list may be paginated into multiple pages.

URI

http://task.example.foo/v2/tasks/since/{split date}

URI Parameters

{split date}: A RFC 3339 compliant date (Zulu time) to be used as split point.

HTTP Method

GET

Resource Formats

Authentication

required

Request Entities

n/a

Responses

204 No Content: No task available yet
303 See Other: Location header contains link to first page of tasks
400 Bad Request: Invalid date

Response Entities

6.7 Retrieve a single task snapshot

Description

Returns a complete set of data of this task, including comments, votes and sumbissions.

URI

http://task.example.foo/v2/task/{task-id}/snapshot

URI Parameters

task-id: task ID

HTTP Method

GET

Resource Formats

application/json

Authentication

required

Request Entities

n/a

Responses

200 OK
404 Not Found

Response Entities

{
   "task":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015"
      },
      "constraints":{
         "time":{
            "start":"2010-06-29T16:00:51.765Z",
            "end":"2010-06-29T19:15:50.000Z"
         },
         "location":{
            "bbox":[
               100.0,
               0.0,
               105.0,
               1.0
            ]
         }
      },
      "title":"foo bar",
      "description":"foo bar asd lorem",
      "creationTime":"2010-07-17T18:54:11.939Z",
      "creator":{
         "link":{
            "rel":"self",
            "href":"http://core/v2/user/123456"
         }
      },
      "votes":{
         "link":{
            "rel":"self",
            "href":"http://task.example.foo/v2/resource/votes"
         },
         "up":123,
         "down":42
      }
   },
   "submissions":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/task/eafbad70-7972-11e0-a1f0-0800200c9a66/submissions"
      },
      "list":[
         {
            "submission":{
               "link":{
                  "rel":"self",
                  "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000"
               },
               "votes":{
                  "link":{
                     "rel":"self",
                     "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000/votes"
                  },
                  "up":123,
                  "down":42
               },
               "document":{
                  "link":{
                     "rel":"self",
                     "href":"http://core/v2/document/550e8400-e29b-11d4-a716-446655440000"
                  }
               },
               "creationTime":"2010-07-17T18:54:11.939Z",
               "creator":{
                  "link":{
                     "rel":"self",
                     "href":"http://core/v2/user/123456"
                  }
               },
               "tags":{
                  "link":{
                     "rel":"self",
                     "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000/tags"
                  },
                  "list":[
                     {
                        "tag":{
                           "link":{
                              "rel":"self",
                              "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
                           },
                           "baseTag":{
                              "link":{
                                 "rel":"self",
                                 "href":"http://task.example.foo/v2/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
                              }
                           },
                           "value":"mytag",
                           "creationTime":"2010-07-17T18:54:11.939Z",
                           "creator":{
                              "link":{
                                 "rel":"self",
                                 "href":"http://core/v2/user/123456"
                              }
                           },
                           "votes":{
                              "link":{
                                 "rel":"self",
                                 "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/submission/550e8400-e29b-11d4-a716-446655440000/tag/ef7987f2bd22f4a8cf236c83a57c1f6b/votes"
                              },
                              "up":12,
                              "down":2
                           }
                        }
                     }
                  ]
               }
            }
         }
      ]
   },
   "comments":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/task/eafbad70-7972-11e0-a1f0-0800200c9a66/comments"
      },
      "list":[
         {
            "comment":{
               "link":{
                  "rel":"self",
                  "href":"http://task.example.foo/v2/task/eafbad70-7972-11e0-a1f0-0800200c9a66/comment/8e252710-77cf-11e0-a1f0-0800200c9a66"
               },
               "content":"blablabla",
               "creationTime":"2010-07-17T18:54:11.939Z",
               "creator":{
                  "link":{
                     "rel":"self",
                     "href":"http://core/v2/user/123456"
                  }
               },
               "votes":{
                  "link":{
                     "rel":"self",
                     "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/tag/ef7987f2bd22f4a8cf236c83a57c1f6b/votes"
                  },
                  "up":12,
                  "down":2
               }
            }
         }
      ]
   },
   "tags":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/resource/tags"
      },
      "list":[
         {
            "tag":{
               "link":{
                  "rel":"self",
                  "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
               },
               "baseTag":{
                  "link":{
                     "rel":"self",
                     "href":"http://task.example.foo/v2/tag/ef7987f2bd22f4a8cf236c83a57c1f6b"
                  }
               },
               "value":"mytag",
               "creationTime":"2010-07-17T18:54:11.939Z",
               "creator":{
                  "link":{
                     "rel":"self",
                     "href":"http://core/v2/user/123456"
                  }
               },
               "votes":{
                  "link":{
                     "rel":"self",
                     "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/tag/ef7987f2bd22f4a8cf236c83a57c1f6b/votes"
                  },
                  "up":12,
                  "down":2
               }
            }
         }
      ]
   }
}

6.8 Retrieve task meta data

Description

Returns all meta data of this task.

URI

http://task.example.foo/v2/task/{task-id}

URI Parameters

task-id: task ID

HTTP Method

GET

Resource Formats

application/json

Authentication

required

Request Entities

n/a

Responses

200 OK
404 Not Found

Response Entities

{
   "task":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015"
      },
      "constraints":{
         "time":{
            "start":"2010-06-29T16:00:51.765Z",
            "end":"2010-06-29T19:15:50.000Z"
         },
         "location":{
            "bbox":[
               100.0,
               0.0,
               105.0,
               1.0
            ]
         }
      },
      "title":"foo bar",
      "description":"foo bar asd lorem",
      "creationTime":"2010-07-17T18:54:11.939Z",
      "creator":{
         "link":{
            "rel":"self",
            "href":"http://core/v2/user/123456"
         }
      },
      "votes":{
         "link":{
            "rel":"self",
            "href":"http://task.example.foo/v2/resource/votes"
         },
         "up":123,
         "down":42
      }
   },
   "submissions":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/task/eafbad70-7972-11e0-a1f0-0800200c9a66/submissions"
      }
   },
   "comments":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/task/eafbad70-7972-11e0-a1f0-0800200c9a66/comments"
      }
   },
   "tags":{
      "link":{
         "rel":"self",
         "href":"http://task.example.foo/v2/task/2671f383-a28c-44d5-b86b-f7f04bb0a015/tags"
      }
   }
}

7. Vote

Description

This resource represents a vote. Users can vote on various resources. The voting URI path is appended to the original URI. The following resources of the Task API can be voted on: Task, Submission, Comment and Tag (for tasks and submissions)

Resource URI

http://task.example.foo/v2/{resource}/vote/user/{user-id}

resource: resource identifier
user-id: user ID

7.1 Get all votes

Description

Returns a summary of all votes for this resource.

URI

http://task.example.foo/v2/{resource}/votes

URI Parameters

{resource}: resource identifier

HTTP Method

GET

Resource Formats

Authentication

required

Request Entities

n/a

Responses

200 OK: Votes in response body.
404 Not Found: Resource not found

Response Entities

{
   "votes":{
  	 "link":{
            "rel":"self",
            "href":"http://task.example.foo/v2/resource/votes"
         },
      "up":123,
      "down":42
   }
}

7.2 Get a vote of the user

Description

Returns the current vote of the user authenticating the request.

URI

http://task.example.foo/v2/{resource}/vote/user/{user-id}

URI Parameters

resource: resource identifier
user-id: user ID

HTTP Method

GET

Resource Formats

Authentication

required

Request Entities

n/a

Responses

200 OK: Vote in response body.
403 Forbidden: Mismatch of voted and authenticated user.
404 Not Found: User has not yet voted

Response Entities

{
   "vote": "up"
}

A response containing an up-vote.

{
   "vote": "down"
}

A response containing a down-vote.

7.3 Undo a vote on a resource

Description

Undos a vote that has been casted before.

URI

http://task.example.foo/v2/{resource}/vote/user/{user-id}

URI Parameters

resource: resource identifier
user-id: user ID

HTTP Method

DELETE

Resource Formats

Authentication

required

Request Entities

n/a

Responses

204 No Content: Vote has been removed.
403 Forbidden: Mismatch of voting and authenticated user.
404 Not Found: No vote found.

Response Entities

n/a

7.4 Vote on a resource

Description

Casts a vote by the user authenticating the request.

URI

http://task.example.foo/v2/{resource}/vote/user/{user-id}/{vote}

URI Parameters

resource: resource identifier
user-id: user ID
{vote}: up or down

HTTP Method

PUT

Resource Formats

Authentication

required

Request Entities

n/a

Responses

202 Accepted: Vote has been casted.
403 Forbidden: Mismatch of voting and authenticated user.

Response Entities

n/a