WADL to RST migration (part 2 - tasks)

This brings the Images API Reference to the glance tree as part of
the effort described here:
https://wiki.openstack.org/wiki/Documentation/Migrate#API_Reference_Plan

This patch contains the tasks part of the Images v2 API reference.

Change-Id: I02ea9052c00c069a03c58b17893a5e93828e172d
This commit is contained in:
bria4010 2016-06-22 17:08:34 -04:00
parent dad3a613bc
commit 011235fb2f
13 changed files with 756 additions and 1 deletions

View File

@ -23,4 +23,4 @@ Image Service APIs
versions/index
v1/index
.. v2/index
v2/index

View File

@ -0,0 +1,26 @@
..
Copyright 2010 OpenStack Foundation
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
:tocdepth: 3
==============================
Image Service API v2 (CURRENT)
==============================
.. rest_expand_all::
.. include:: tasks.inc
.. include:: tasks-schemas.inc

View File

@ -0,0 +1,72 @@
{
"name": "task",
"properties": {
"created_at": {
"description": "Datetime when this resource was created",
"type": "string"
},
"expires_at": {
"description": "Datetime when this resource would be subject to removal",
"type": [
"null",
"string"
]
},
"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"
},
"input": {
"description": "The parameters required by task, JSON blob",
"type": [
"null",
"object"
]
},
"message": {
"description": "Human-readable informative message only included when appropriate (usually on failure)",
"type": "string"
},
"owner": {
"description": "An identifier for the owner of this task",
"type": "string"
},
"result": {
"description": "The result of current task, JSON blob",
"type": [
"null",
"object"
]
},
"schema": {
"readOnly": true,
"type": "string"
},
"self": {
"readOnly": true,
"type": "string"
},
"status": {
"description": "The current status of this task",
"enum": [
"pending",
"processing",
"success",
"failure"
],
"type": "string"
},
"type": {
"description": "The type of task represented by this content",
"enum": [
"import"
],
"type": "string"
},
"updated_at": {
"description": "Datetime when this resource was updated",
"type": "string"
}
}
}

View File

@ -0,0 +1,71 @@
{
"links": [
{
"href": "{schema}",
"rel": "describedby"
}
],
"name": "tasks",
"properties": {
"schema": {
"type": "string"
},
"tasks": {
"items": {
"name": "task",
"properties": {
"created_at": {
"description": "Datetime when this resource was created",
"type": "string"
},
"expires_at": {
"description": "Datetime when this resource would be subject to removal",
"type": [
"null",
"string"
]
},
"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"
},
"owner": {
"description": "An identifier for the owner of this task",
"type": "string"
},
"schema": {
"readOnly": true,
"type": "string"
},
"self": {
"readOnly": true,
"type": "string"
},
"status": {
"description": "The current status of this task",
"enum": [
"pending",
"processing",
"success",
"failure"
],
"type": "string"
},
"type": {
"description": "The type of task represented by this content",
"enum": [
"import"
],
"type": "string"
},
"updated_at": {
"description": "Datetime when this resource was updated",
"type": "string"
}
}
},
"type": "array"
}
}
}

View File

@ -0,0 +1,11 @@
{
"type": "import",
"input": {
"import_from": "http://app.catalog.openstack.org/groovy-image",
"import_from_format": "qcow2",
"image_properties": {
"disk_format": "vhd",
"container_format": "ovf"
}
}
}

View File

@ -0,0 +1,20 @@
{
"created_at": "2016-06-24T14:57:19Z",
"id": "bb480de2-7077-4ea9-bbe9-be1891290d3e",
"input": {
"image_properties": {
"container_format": "ovf",
"disk_format": "vhd"
},
"import_from": "http://app.catalog.openstack.org/groovy-image",
"import_from_format": "qcow2"
},
"message": "",
"owner": "fa6c8c1600f4444281658a23ee6da8e8",
"result": null,
"schema": "/v2/schemas/task",
"self": "/v2/tasks/bb480de2-7077-4ea9-bbe9-be1891290d3e",
"status": "pending",
"type": "import",
"updated_at": "2016-06-24T14:57:19Z"
}

View File

@ -0,0 +1,21 @@
{
"created_at": "2016-06-24T14:57:20Z",
"expires_at": "2016-06-26T14:57:20Z",
"id": "bb480de2-7077-4ea9-bbe9-be1891290d3e",
"input": {
"image_properties": {
"container_format": "ovf",
"disk_format": "vhd"
},
"import_from": "http://app.catalog.openstack.org/groovy-image",
"import_from_format": "qcow2"
},
"message": "Task failed due to Internal Error",
"owner": "fa6c8c1600f4444281658a23ee6da8e8",
"result": null,
"schema": "/v2/schemas/task",
"self": "/v2/tasks/bb480de2-7077-4ea9-bbe9-be1891290d3e",
"status": "failure",
"type": "import",
"updated_at": "2016-06-24T14:57:20Z"
}

View File

@ -0,0 +1,20 @@
{
"created_at": "2016-06-24T14:40:19Z",
"id": "231c311d-3557-4e23-afc4-6d98af1419e7",
"input": {
"image_properties": {
"container_format": "ovf",
"disk_format": "vhd"
},
"import_from": "http://example.com",
"import_from_format": "qcow2"
},
"message": "",
"owner": "fa6c8c1600f4444281658a23ee6da8e8",
"result": null,
"schema": "/v2/schemas/task",
"self": "/v2/tasks/231c311d-3557-4e23-afc4-6d98af1419e7",
"status": "processing",
"type": "import",
"updated_at": "2016-06-24T14:40:20Z"
}

View File

@ -0,0 +1,23 @@
{
"created_at": "2016-06-29T16:13:07Z",
"expires_at": "2016-07-01T16:13:07Z",
"id": "805f47d2-8814-4cd7-bef3-37037389a998",
"input": {
"image_properties": {
"container_format": "ovf",
"disk_format": "vhd"
},
"import_from": "https://apps.openstack.org/excellent-image",
"import_from_format": "qcow2"
},
"message": "",
"owner": "02a7fb2dd4ef434c8a628c511dcbbeb6",
"result": {
"image_id": "2b61ed2b-f800-4da0-99ff-396b742b8646"
},
"schema": "/v2/schemas/task",
"self": "/v2/tasks/805f47d2-8814-4cd7-bef3-37037389a998",
"status": "success",
"type": "import",
"updated_at": "2016-06-29T16:13:07Z"
}

View File

@ -0,0 +1,26 @@
{
"first": "/v2/tasks",
"schema": "/v2/schemas/tasks",
"tasks": [
{
"created_at": "2016-06-24T14:44:19Z",
"id": "08b7e1c8-3821-4f54-b3b8-d6655d178cdf",
"owner": "fa6c8c1600f4444281658a23ee6da8e8",
"schema": "/v2/schemas/task",
"self": "/v2/tasks/08b7e1c8-3821-4f54-b3b8-d6655d178cdf",
"status": "processing",
"type": "import",
"updated_at": "2016-06-24T14:44:19Z"
},
{
"created_at": "2016-06-24T14:40:19Z",
"id": "231c311d-3557-4e23-afc4-6d98af1419e7",
"owner": "fa6c8c1600f4444281658a23ee6da8e8",
"schema": "/v2/schemas/task",
"self": "/v2/tasks/231c311d-3557-4e23-afc4-6d98af1419e7",
"status": "processing",
"type": "import",
"updated_at": "2016-06-24T14:40:20Z"
}
]
}

View File

@ -0,0 +1,195 @@
# variables in header
Content-Type-json:
description: |
The media type descriptor for the request body. Use ``application/json``.
in: header
required: true
type: string
# variables in path
task_id:
description: |
The identifier for the task, a UUID.
in: path
required: true
type: string
# variables in query
limit:
description: |
Requests a page size of items. Returns a number of items up to a limit
value. Use the ``limit`` parameter to make an initial limited request and
use the ID of the last-seen item from the response as the ``marker``
parameter value in a subsequent limited request.
in: query
required: false
type: integer
marker:
description: |
The ID of the last-seen item. Use the ``limit`` parameter to make an
initial limited request and use the ID of the last-seen item from the
response as the ``marker`` parameter value in a subsequent limited request.
in: query
required: false
type: string
sort_dir:
description: |
Sorts the response by a set of one or more sort direction and attribute
(``sort_key``) combinations. A valid value for the sort direction is
``asc`` (ascending) or ``desc`` (descending). If you omit the sort
direction in a set, the default is ``desc``.
in: query
required: false
type: string
sort_key:
description: |
Sorts the response by one of the following attributes: ``created_at``,
``expires_at``, ``status``, ``type``, ``updated_at``. Default is
``created_at``.
in: query
required: false
type: string
status-in-query:
description: |
Filters the response by a task status. A valid value is ``pending``,
``processing``, ``success``, or ``failure``.
in: query
required: false
type: string
type-in-query:
description: |
Filters the response by a task type. A valid value is ``import``.
in: query
required: false
type: string
# variables in body
created_at:
description: |
The date and time when the task was created.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_.
in: body
required: true
type: string
expires_at:
description: |
The date and time when the task is subject to removal. While the *task
object*, that is, the record describing the task is subject to deletion,
the result of the task (for example, an imported image) still exists.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_.
This value is only set when the task reaches status ``success`` or
``failure``. Otherwise its value is ``null``. It may not appear in
the response when its value is ``null``.
in: body
required: true
type: string
first:
description: |
The URI for the first page of response.
in: body
required: true
type: string
id:
description: |
The UUID of the task.
in: body
required: true
type: string
input:
description: |
A JSON object specifying the input parameters to the task. Consult your
cloud provider's documentation for details.
in: body
required: true
type: object
message:
description: |
Human-readable text, possibly an empty string, usually displayed in an
error situation to provide more information about what has occurred.
in: body
required: true
type: string
next:
description: |
The URI for the next page of response. Will not be present on the last
page of the response.
in: body
required: true
type: string
owner:
description: |
An identifier for the owner of the task, usually the tenant ID.
in: body
required: true
type: string
result:
description: |
A JSON object specifying information about the ultimate outcome of the
task. Consult your cloud provider's documentation for details.
in: body
required: true
type: object
schema-task:
description: |
The URI for the schema describing an image task.
in: body
required: true
type: string
schema-tasks:
description: |
The URI for the schema describing an image task list.
in: body
required: true
type: string
self:
description: |
A URI for this task.
in: body
required: true
type: string
status:
description: |
The current status of this task. The value can be ``pending``,
``processing``, ``success`` or ``failure``.
in: body
required: true
type: string
tasks:
description: |
A list of sparse *task* objects. Each object contains the following
fields:
- ``created_at``
- ``id``
- ``owner``
- ``schema``
- ``self``
- ``status``
- ``type``
- ``updated_at``
in: body
required: true
type: array
type:
description: |
The type of task represented by this content.
in: body
required: true
type: string
updated_at:
description: |
The date and time when the task was updated.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_.
If the ``updated_at`` date and time stamp is not set, its value is
``null``.
in: body
required: true
type: string

View File

@ -0,0 +1,72 @@
.. -*- rst -*-
Task Schemas
************
Gets a JSON-schema document that represents an individual task and a
list of tasks.
.. _tasks-schema:
Show tasks schema
~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v2/schemas/tasks
*(Since Images v2.2)*
Shows a JSON schema document that represents a list of *tasks*.
An tasks list entity is a container of entities containing abbreviated
information about individual tasks.
The following schema is solely an example. Consider only the
response to the API call as authoritative.
Normal response codes: 200
Error response codes: 401
Request
-------
This operation has no request parameters and does not accept a request body.
Response Example
----------------
.. literalinclude:: samples/schemas-tasks-list-response.json
:language: json
.. _task-schema:
Show task schema
~~~~~~~~~~~~~~~~
.. rest_method:: GET /v2/schemas/task
*(Since Images v2.2)*
Shows a JSON schema document that represents an *task* entity.
The following schema is solely an example. Consider only the
response to the API call as authoritative.
Normal response codes: 200
Error response codes: 401
Request
-------
This operation has no request parameters and does not accept a request body.
Response Example
----------------
.. literalinclude:: samples/schemas-task-show-response.json
:language: json

198
api-ref/source/v2/tasks.inc Normal file
View File

@ -0,0 +1,198 @@
.. -*- rst -*-
Tasks
*****
Creates, lists, and shows details for tasks.
*(Since API v2.2)*
General Information
~~~~~~~~~~~~~~~~~~~
**API Status**
This API was made admin-only by default in the OpenStack Mitaka release. Thus
the following calls may not be available to end users in your cloud. Please
consult your cloud provider's documentation for more information.
**Conceptual Overview**
Please see the `Tasks <http://docs.openstack.org/developer/glance/tasks.html>`_
section of the Glance Developers Documentation for a conceptual overview of
tasks.
**Task Status**
The possible status values for tasks are presented in the following table.
.. list-table::
:header-rows: 1
* - Status
- Description
* - pending
- The task is waiting for execution.
* - processing
- Execution of the task is underway.
* - success
- The task completed successfully. The ``result`` element should be
populated.
* - failure
- The task failed to complete. The ``message`` element should be a
non-empty string.
Create task
~~~~~~~~~~~
.. rest_method:: POST /v2/tasks
Creates a task.
Normal response codes: 201
Error response codes: 401, 413, 415
Request
-------
.. rest_parameters:: tasks-parameters.yaml
- type: type
- input: input
Request Example
---------------
.. literalinclude:: samples/task-create-request.json
:language: json
Response Parameters
-------------------
.. rest_parameters:: tasks-parameters.yaml
- created_at: created_at
- id: id
- input: input
- message: message
- owner: owner
- result: result
- schema: schema-task
- self: self
- status: status
- type: type
- updated_at: updated_at
Response Example
----------------
.. literalinclude:: samples/task-create-response.json
:language: json
List tasks
~~~~~~~~~~
.. rest_method:: GET /v2/tasks
Lists tasks.
Normal response codes: 200
Error response codes: 403, 404, 413
Request
-------
.. rest_parameters:: tasks-parameters.yaml
- limit: limit
- marker: marker
- sort_dir: sort_dir
- sort_key: sort_key
- status: status-in-query
- type: type-in-query
Response Parameters
-------------------
.. rest_parameters:: tasks-parameters.yaml
- first: first
- next: next
- schema: schema-tasks
- tasks: tasks
Response Example
----------------
.. literalinclude:: samples/tasks-list-response.json
:language: json
Show task details
~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v2/tasks/{task_id}
Shows details for a task.
Normal response codes: 200
Error response codes: 404
Request
-------
.. rest_parameters:: tasks-parameters.yaml
- task_id: task_id
Response Parameters
-------------------
.. rest_parameters:: tasks-parameters.yaml
- created_at: created_at
- expires_at: expires_at
- id: id
- input: input
- message: message
- owner: owner
- result: result
- schema: schema-task
- self: self
- status: status
- type: type
- updated_at: updated_at
Response Example (task status: processing)
------------------------------------------
.. literalinclude:: samples/task-show-processing-response.json
:language: json
Response Example (task status: success)
------------------------------------------
.. literalinclude:: samples/task-show-success-response.json
:language: json
Response Example (task status: failure)
---------------------------------------
.. literalinclude:: samples/task-show-failure-response.json
:language: json