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

1. User posts a request to /v2/tasks
2. Glance returns a 201 with Location: /v2/tasks/{task-uuid}
   • The resource at /v2/tasks/{task-uuid} will be an expirable entity
3. User polls /v2/tasks/{task-uuid} for status information on the requested task
4. 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 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"
        }
    ], 

}

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