From 5417d83ec333683536edbc2c835a85cc629ad413 Mon Sep 17 00:00:00 2001 From: Sergey Nikitin Date: Wed, 8 Jun 2016 16:16:45 +0300 Subject: [PATCH] api-ref: added docs for microversion 2.26 Part of bp:tag-instances Part of bp:api-ref-in-rst Change-Id: Ifd0d518d086719eb248b442359c272b1799544c6 --- api-ref/source/index.rst | 1 + api-ref/source/os-server-tags.inc | 187 ++++++++++++++++++++++++++++++ api-ref/source/parameters.yaml | 34 +++++- 3 files changed, 218 insertions(+), 4 deletions(-) create mode 100644 api-ref/source/os-server-tags.inc diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index f4ce4c0115af..626f5ee9116f 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -46,6 +46,7 @@ .. include:: os-migrations.inc .. include:: os-quota-sets.inc .. include:: os-server-groups.inc +.. include:: os-server-tags.inc .. include:: os-services.inc .. include:: os-simple-tenant-usage.inc .. include:: os-server-external-events.inc diff --git a/api-ref/source/os-server-tags.inc b/api-ref/source/os-server-tags.inc new file mode 100644 index 000000000000..66ee7896897d --- /dev/null +++ b/api-ref/source/os-server-tags.inc @@ -0,0 +1,187 @@ +.. -*- rst -*- + +============================= + Server tags (servers, tags) +============================= + +Lists tags, creates, replaces or deletes one or more tags for a server, checks +the existence of a tag for a server. + +Available since version 2.26 + +Tags have the following restrictions: + +- Tag is a Unicode bytestring no longer than 60 characters. + +- Tags are case sensitive. + +- '/' is not allowed to be in a tag name + +- Comma is not allowed to be in a tag name in order to simplify requests that + specify lists of tags + +- All other characters are allowed to be in a tag name + +- Each server can have up to 50 tags. + +List Tags +========= + +.. rest_method:: GET /servers/{server_id}/tags + +Lists all tags for a server. + +Normal response codes: 200 + +Error response codes: unauthorized(401), forbidden(403), itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - server_id: server_id_path + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - tags: tags + +**Example List Tags:** + +.. literalinclude:: ../../doc/api_samples/os-server-tags/v2.26/server-tags-index-resp.json + :language: javascript + +Check Tag Existence +=================== + +.. rest_method:: GET /servers/{server_id}/tags/{tag} + +Checks tag existence on the server. If tag exists response with 204 status code +will be returned. Otherwise returns 404. + +Normal response codes: 204 + +Error response codes: unauthorized(401), forbidden(403), itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - server_id: server_id_path + - tag: tag + +Replace Tags +============ + +.. rest_method:: PUT /servers/{server_id}/tags + +Replaces all tags on specified server with the new set of tags. + +Normal response codes: 200 + +Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - server_id: server_id_path + - tags: tags + +**Example Replace Tags:** + +.. literalinclude:: ../../doc/api_samples/os-server-tags/v2.26/server-tags-put-all-req.json + :language: javascript + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - tags: tags + +**Example Replace Tags:** + +.. literalinclude:: ../../doc/api_samples/os-server-tags/v2.26/server-tags-put-all-resp.json + :language: javascript + +Add a Single Tag +================ + +.. rest_method:: PUT /servers/{server_id}/tags/{tag} + +Adds a single tag to the server if server has no specified tag. Response code +in this case is 201. + +If the server has specified tag just returns 204. + +Normal response codes: 201, 204 + +Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - server_id: server_id_path + - tag: tag + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - Location: tag_location + +Delete a Single Tag +=================== + +.. rest_method:: DELETE /servers/{server_id}/tags/{tag} + +Deletes a single tag from the specified server. + +Normal response codes: 204 + +Error response codes: unauthorized(401), forbidden(403), itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - server_id: server_id_path + - tag: tag + +Response +-------- + +There is no body content for the response of a successful DELETE query + +Delete All Tags +=============== + +.. rest_method:: DELETE /servers/{server_id}/tags + +Deletes all tags from the specified server. + +Normal response codes: 204 + +Error response codes: unauthorized(401), forbidden(403), itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - server_id: server_id_path + +Response +-------- + +There is no body content for the response of a successful DELETE query diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 2b7d4be6e177..bfa2eb085b65 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -1,4 +1,12 @@ # variables in header +tag_location: + description: | + The location of the tag. It's individual tag URL which can be used for + checking the existence of the tag on the server or deleting the tag from the server. + in: header + required: true + type: string + min_version: 2.26 x-openstack-request-id: description: > A unique ID for tracking the request. The request ID associated with the request @@ -252,6 +260,13 @@ snapshot_id_2: in: path required: true type: string +tag: + description: | + The tag as a string. + in: path + required: true + type: string + min_version: 2.26 tenant_id: description: | The UUID of the tenant in a multi-tenancy cloud. @@ -496,7 +511,8 @@ not_tags_any_query: type: string description: | A list of tags to filter the server list by. Servers that don't - match any tags in this list will be returned. + match any tags in this list will be returned. Boolean expression in this + case is 'NOT (t1 OR t2)'. Tags in query must be separated by comma. min_version: 2.26 not_tags_query: in: query @@ -504,7 +520,8 @@ not_tags_query: type: string description: | A list of tags to filter the server list by. Servers that don't - match all tags in this list will be returned. + match all tags in this list will be returned. Boolean expression in this + case is 'NOT (t1 AND t2)'. Tags in query must be separated by comma. min_version: 2.26 reservation_id_query: in: query @@ -568,7 +585,8 @@ tags_any_query: type: string description: | A list of tags to filter the server list by. Servers that match - any tag in this list will be returned. + any tag in this list will be returned. Boolean expression in this + case is 't1 OR t2'. Tags in query must be separated by comma. min_version: 2.26 tags_query: in: query @@ -576,7 +594,8 @@ tags_query: type: string description: | A list of tags to filter the server list by. Servers that match - all tags in this list will be returned. + all tags in this list will be returned. Boolean expression in this + case is 't1 AND t2'. Tags in query must be separated by comma. min_version: 2.26 type_1: description: | @@ -3374,6 +3393,13 @@ suspend: in: body required: true type: string +tags: + description: | + A list of tags. The maximum count of tags in this list is 50. + in: body + required: true + type: array + min_version: 2.26 tenant_id_body: description: | The UUID of the tenant in a multi-tenancy cloud.