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 Properties

(no ordering, just using the numerals to keep count)

1. id
2. type
3. status
4. owner : this is whatever is being used as the image owner in this glance installation
5. input : task "parameters"
6. result
7. created_at
8. updated_at
9. expires_at
10. message

Task Schema

A json-schema for the task entity will be available at the URI /v2/schemas/tasks

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",
            "required": true
         },
        "owner": {
            "description": "An identifier for the owner of this task", 
            "type": "string",
            "required": true     
        },
        "type" : {
            "description": "The type of task represented by this content",
            "enum": [
                "import",
                "export",
                "clone"
            ],
            "type": "string",
            "required": true
        },
        "status" : {
            "description": "The current status of this task.", 
            "enum": [
                "pending",
                "processing",
                "success",
                "failure"
            ],
            "type": "string",
            "required": true
        },
        "created_at": {
            "description": "Datetime when this resource was created",
            "type": "string",
            "required": true
        },
         "updated_at": {
            "description": "Datetime when this resource was most recently updated",
            "type": "string",
            "required": true
        },
        "expires_at": {
            "description": "Datetime when this resource is subject to removal",
            "type": "string"
        },
       "message": {
           "description": "Human-readable informative message only included when appropriate (usually on failure)",
           "type": "string",
        },
        "input": {
           "description": "The input parameters for this task",
           "type": "object",
           "required": true
        },
       "result": {
           "description": "Informatic results of this task",
           "type": "object",
       },
    },
    "links": [
        {
            "href": "{self}", 
            "rel": "self"
        }, 
        {
            "href": "{file}", 
            "rel": "enclosure"
        }, 
        {
            "href": "{schema}", 
            "rel": "describedby"
        }
    ], 
}

Task Response Body

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

Task Request Schema

The basic tasks request is defined by the following JSON schema.

{
    "name": "task_request",
    "properties": {
        "type": {
            "description": "The type of task requested",
            "enum": [
                "import",
                "export",
                "clone"
            ],
            "type": "string",
            "required": true
        },
        "input": {
            "description": "The input parameters for this task.  Valid content depends on the task type, see the documentation for details.",
            "type": "object",
            "required": true
        }
    } 
}

Task Request Body

The basic task request will be Content-type: application/json and will adhere to the task_request json schema described above.

Task States

Tasks will have the following states:

• pending : a task has been created, but Glance (via async worker or whatever) hasn't begun to execute the task yet
• processing : the task is underway
• success : the task has complete successfully
• failure : something went wrong, the task was not able to complete

In the case of failure, it's expected that the task resource will contain a message explaining what went wrong.

Requests

Create a Task

POST /v2/tasks

Request body must be appropriate for the task_type.

Display Task Detail

GET /v2/tasks/{task_id}

Returns a task response as defined above.

List Tasks

GET /v2/tasks

Returns a list of tasks owned by the user making the request.

Query Parameters

We'll want to allow filtering on the task type, e.g.,

GET /v2/tasks?type=import

would return all non-expired import tasks owned by the user making the request. The allowed values are 'import', 'export', 'clone'.

Open Questions

1. What do we return when a user makes a GET for a task UUID that exists, but they don't own?
   • 401 or 404?
2. The task request will return a 200 even when the task_status is 'failure' (since the task response itself is being returned OK). Some of these failures will be for things like not-found, format-not-supported, conflict ... this will be mentioned in the 'message' field, but do we want to have a separate failure code or something to make it easier for an API user to extract this info?

Proposed Tasks

1. import
2. export
3. clone

Related Documents

• Havana summit discussion etherpad (see bottom of pad)
• original blueprint proposal
• mailing list discussion of original proposal
• mailing list discussion of this proposal
• etherpad of further discussion refining this proposal