Difference between revisions of "Glance-tasks-api"
m |
m (→Task Schema) |
||
Line 85: | Line 85: | ||
} | } | ||
</pre> | </pre> | ||
+ | |||
+ | Actually, it may be better to just use this as a proto-schema and define a specific one for each task type, available at, e.g., | ||
+ | * /v2/schemas/tasks/import | ||
+ | * /v2/schemas/tasks/export | ||
+ | * /v2/schemas/tasks/clone | ||
== Tasks Requests == | == Tasks Requests == |
Revision as of 21:24, 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": { "id": { "description": "An identifier for the image", "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$", "type": "string" }, "task_type" : { "description": "The type of task represented by this content", "enum": [ "import", "export", "clone" ], "type": "string" }, "task_status" : { "description": "The current status of this task.", "enum": [ "queued", "preparing", "transferring", "processing", "verifying", "success", "failure" ], "type": "string" }, "expires_at": { "description": "Datetime when this resource is subject to removal", "type": "string", "required" : false }, "message": { "description": "Human-readable informative message only included when appropriate (usually on failure)", "type": "string", "required" : false, } }, "links": [ { "href": "{self}", "rel": "self" }, { "href": "{file}", "rel": "enclosure" }, { "href": "{schema}", "rel": "describedby" } ], }
Actually, it may be better to just use this as a proto-schema and define a specific one for each task type, available at, e.g.,
- /v2/schemas/tasks/import
- /v2/schemas/tasks/export
- /v2/schemas/tasks/clone
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