diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 53ca61d006..22f1e86bb1 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -23,4 +23,4 @@ Image Service APIs versions/index v1/index -.. v2/index + v2/index diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst new file mode 100644 index 0000000000..37c1bf1caf --- /dev/null +++ b/api-ref/source/v2/index.rst @@ -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 diff --git a/api-ref/source/v2/samples/schemas-task-show-response.json b/api-ref/source/v2/samples/schemas-task-show-response.json new file mode 100644 index 0000000000..044f48c013 --- /dev/null +++ b/api-ref/source/v2/samples/schemas-task-show-response.json @@ -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" + } + } +} diff --git a/api-ref/source/v2/samples/schemas-tasks-list-response.json b/api-ref/source/v2/samples/schemas-tasks-list-response.json new file mode 100644 index 0000000000..660dbe1e10 --- /dev/null +++ b/api-ref/source/v2/samples/schemas-tasks-list-response.json @@ -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" + } + } +} diff --git a/api-ref/source/v2/samples/task-create-request.json b/api-ref/source/v2/samples/task-create-request.json new file mode 100644 index 0000000000..0809010cd8 --- /dev/null +++ b/api-ref/source/v2/samples/task-create-request.json @@ -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" + } + } +} diff --git a/api-ref/source/v2/samples/task-create-response.json b/api-ref/source/v2/samples/task-create-response.json new file mode 100644 index 0000000000..cb491e187a --- /dev/null +++ b/api-ref/source/v2/samples/task-create-response.json @@ -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" +} diff --git a/api-ref/source/v2/samples/task-show-failure-response.json b/api-ref/source/v2/samples/task-show-failure-response.json new file mode 100644 index 0000000000..283753d648 --- /dev/null +++ b/api-ref/source/v2/samples/task-show-failure-response.json @@ -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" +} diff --git a/api-ref/source/v2/samples/task-show-processing-response.json b/api-ref/source/v2/samples/task-show-processing-response.json new file mode 100644 index 0000000000..313b8fd9d0 --- /dev/null +++ b/api-ref/source/v2/samples/task-show-processing-response.json @@ -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" +} diff --git a/api-ref/source/v2/samples/task-show-success-response.json b/api-ref/source/v2/samples/task-show-success-response.json new file mode 100644 index 0000000000..b422525bb9 --- /dev/null +++ b/api-ref/source/v2/samples/task-show-success-response.json @@ -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" +} diff --git a/api-ref/source/v2/samples/tasks-list-response.json b/api-ref/source/v2/samples/tasks-list-response.json new file mode 100644 index 0000000000..2bf39df691 --- /dev/null +++ b/api-ref/source/v2/samples/tasks-list-response.json @@ -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" + } + ] +} diff --git a/api-ref/source/v2/tasks-parameters.yaml b/api-ref/source/v2/tasks-parameters.yaml new file mode 100644 index 0000000000..6b5a6a583d --- /dev/null +++ b/api-ref/source/v2/tasks-parameters.yaml @@ -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 + `_. + 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 + `_. + + 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 + `_. + + If the ``updated_at`` date and time stamp is not set, its value is + ``null``. + in: body + required: true + type: string diff --git a/api-ref/source/v2/tasks-schemas.inc b/api-ref/source/v2/tasks-schemas.inc new file mode 100644 index 0000000000..5b777f9273 --- /dev/null +++ b/api-ref/source/v2/tasks-schemas.inc @@ -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 diff --git a/api-ref/source/v2/tasks.inc b/api-ref/source/v2/tasks.inc new file mode 100644 index 0000000000..be9cda0d64 --- /dev/null +++ b/api-ref/source/v2/tasks.inc @@ -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 `_ +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