Glance-tasks-api

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
- 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:

{
    "name": "task",
    "properties": {
        "id": {
            "description": "An identifier for the task", 
            "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

OK, you've got the basic idea. I realized I'm doing this backwards. The decision about whether each task gets its own schema or whether they can be combined into a single schema, or a single schema that references another schema to give the details for that kind of task should wait until after we've figured out what each task looks like. Same deal with the requests/responses.

Tasks Requests

The basic tasks request will be Content-type: application/json and will look something like this:

{
    "task-type": "{task-name}",
    "task-info": {
         /* content will depend on the task type */
    } 
}

Or there may be a different one for each task, still working on this.

Tasks Response

The basic tasks response will be Content-type: application/json and will adhere to the json schema described above.