Difference between revisions of "Glance-tasks-api"
m |
|||
| Line 14: | Line 14: | ||
#** if the task was not successful, an informative message | #** if the task was not successful, an informative message | ||
#* the expiration datetime of the tasks resource itself | #* the expiration datetime of the tasks resource itself | ||
| + | |||
| + | == Task Entities == | ||
| + | An task entity is represented by a JSON-encoded data structure. | ||
| + | |||
| + | An task entity has an identifier (id) that is guaranteed to be unique within the endpoint to which it belongs. The id is used as a token in request URIs to interact with that specific task. | ||
| + | |||
| + | An task is always guaranteed to have the following attributes: id, type, status, and self. The other attributes defined in the task schema below are guaranteed to be defined, but will only be returned with a task entity if they have been explicitly set. | ||
| + | |||
| + | == Task Schema == | ||
| + | A json-schema for the task entity will be available at the URI /v2/schemas/task | ||
| + | |||
| + | And it goes a little something like this: | ||
| + | <pre> | ||
| + | { | ||
| + | "name": "task", | ||
| + | "properties": { | ||
| + | "type" : { | ||
| + | "description": "The type of task represented by this content", | ||
| + | "enum": [ | ||
| + | "import", | ||
| + | "export", | ||
| + | "clone" | ||
| + | ], | ||
| + | "type": "string" | ||
| + | }, | ||
| + | "status" : { | ||
| + | "description": "The current status of this task.", | ||
| + | "enum": [ | ||
| + | "queued", | ||
| + | "preparing", | ||
| + | "transferring", | ||
| + | "processing", | ||
| + | "verifying", | ||
| + | "success", | ||
| + | "failure", | ||
| + | ], | ||
| + | "type": "string" | ||
| + | } | ||
| + | } | ||
| + | "links": [ | ||
| + | { | ||
| + | "href": "{self}", | ||
| + | "rel": "self" | ||
| + | }, | ||
| + | { | ||
| + | "href": "{file}", | ||
| + | "rel": "enclosure" | ||
| + | }, | ||
| + | { | ||
| + | "href": "{schema}", | ||
| + | "rel": "describedby" | ||
| + | } | ||
| + | ], | ||
| + | |||
| + | } | ||
| + | </pre> | ||
| + | |||
| + | == Tasks Requests == | ||
| + | The basic tasks request will be Content-type: application/json and will look like this: | ||
| + | <pre> | ||
| + | { | ||
| + | "task-type": "{task-name}", | ||
| + | "task-info": { | ||
| + | /* content will depend on the task type */ | ||
| + | } | ||
| + | } | ||
| + | </pre> | ||
| + | |||
| + | == Tasks Response == | ||
| + | The basic tasks response will be Content-type | ||
Revision as of 16:06, 16 July 2013
Contents
Overview
This proposal unifies the new upload workflow, new download workflow, and image cloning blueprints in an extensible, consistent, and easy-to-learn way.
General Workflow
- User posts a request to /v2/tasks
- Glance returns a 201 with Location: /v2/tasks/{task-uuid}
- The resource at /v2/tasks/{task-uuid} will be an expirable entity
- User polls /v2/tasks/{task-uuid} for status information on the requested task
- Eventually, when the task is completed, the resource will contain
- task result information, e.g.,
- if the task was successful, the location of the result of the task
- for import or clone tasks, this will be an /images resource
- for export, it will be a location where the exported item may be retrieved
- if the task was not successful, an informative message
- if the task was successful, the location of the result of the task
- the expiration datetime of the tasks resource itself
- task result information, e.g.,
Task Entities
An task entity is represented by a JSON-encoded data structure.
An task entity has an identifier (id) that is guaranteed to be unique within the endpoint to which it belongs. The id is used as a token in request URIs to interact with that specific task.
An task is always guaranteed to have the following attributes: id, type, status, and self. The other attributes defined in the task schema below are guaranteed to be defined, but will only be returned with a task entity if they have been explicitly set.
Task Schema
A json-schema for the task entity will be available at the URI /v2/schemas/task
And it goes a little something like this:
{
"name": "task",
"properties": {
"type" : {
"description": "The type of task represented by this content",
"enum": [
"import",
"export",
"clone"
],
"type": "string"
},
"status" : {
"description": "The current status of this task.",
"enum": [
"queued",
"preparing",
"transferring",
"processing",
"verifying",
"success",
"failure",
],
"type": "string"
}
}
"links": [
{
"href": "{self}",
"rel": "self"
},
{
"href": "{file}",
"rel": "enclosure"
},
{
"href": "{schema}",
"rel": "describedby"
}
],
}
Tasks Requests
The basic tasks request will be Content-type: application/json and will look like this:
{
"task-type": "{task-name}",
"task-info": {
/* content will depend on the task type */
}
}
Tasks Response
The basic tasks response will be Content-type
