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