From e131317430b0c2b3737dae3a76f875c308301685 Mon Sep 17 00:00:00 2001 From: Sean Dague Date: Fri, 6 May 2016 08:37:03 -0400 Subject: [PATCH] api-ref: update parameter validation on servers This updates all the v2.1 parameters for servers, as well as some of the microversions added parameters. It makes us more accurate than the existing api-site. This specificially *does not* include the additional response parameters for microversions > 2.1 (tags, ext attrs for ec2, etc). Part of bp:api-ref-in-rst Change-Id: Ic03c0e6486a300c3cd724b798850dedeae014faf --- api-ref/source/parameters.yaml | 132 +++++++++++++++++++++++++++++++-- api-ref/source/servers.inc | 132 ++++++++++++++++++++++----------- 2 files changed, 213 insertions(+), 51 deletions(-) diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index db1ad89f7577..6ac27a60d299 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -278,7 +278,15 @@ all_projects: type: boolean all_tenants: description: | - Specify the ``all_tenants=1`` query parameter to ping instances for all tenants. + Specify the ``all_tenants=1`` query parameter to ping instances + for all tenants. By default this is only allowed by admin users. + in: query + required: false + type: integer +all_tenants_query: + description: | + Specify the ``all_tenants=1`` query parameter to list all instances + for all projects. By default this is only allowed by admin users. in: query required: false type: integer @@ -320,9 +328,20 @@ changes-since: in: query required: false type: string -changes-since_1: +changes_since_server: description: | - Filters the response by a date and time stamp when the server last changed status. + Filters the response by a date and time stamp when the server last + changed status. To help keep track of changes this may also return + recently deleted servers. + + The date and time stamp format is `ISO 8601 `_: + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + The ``±hh:mm`` value, if included, returns the time zone as an offset from UTC. + For example, ``2015-08-27T09:49:58-05:00``. + If you omit the time zone, the UTC time zone is assumed. in: query required: false type: string @@ -337,6 +356,15 @@ delete_info: in: query required: true type: string +deleted_query: + in: query + required: false + type: boolean + description: | + Show deleted items. In some circumstances deleted items will still + be accessible via the backend database, however there is no + contract on how long, so this parameter should be used with + caution. It is typically only available to administrators. exclude: description: | Specify ``exclude=uuid[,uuid...]`` to exclude the instances from the results. @@ -370,6 +398,19 @@ include: in: query required: false type: string +ip_query: + description: | + An IPv4 address to filter results by. + in: query + required: false + type: string +ip6_query: + description: | + An IPv6 address to filter results by. + in: query + required: false + type: string + min_version: 2.5 limit: description: | Requests a page size of items. Returns a number of items up to a limit value. @@ -411,6 +452,12 @@ minRam_1: in: query required: false type: integer +reservation_id_query: + in: query + required: false + type: string + description: | + A reservation id as returned by a servers multiple create call. server_name_query: description: | Filters the response by a server name, as a string. You can use regular expressions @@ -465,6 +512,40 @@ server_status_query: in: query required: false type: string +# TODO(sdague): when server-tags actually get documented, these should +# be updated. +tags_query: + in: query + required: false + type: string + description: | + A list of tags to filter the server list by. Servers that match + all tags in this list will be returned. + min_version: 2.26 +tags_any_query: + in: query + required: false + type: string + description: | + A list of tags to filter the server list by. Servers that match + any tag in this list will be returned. + min_version: 2.26 +not_tags_query: + in: query + required: false + 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. + min_version: 2.26 +not_tags_any_query: + in: query + required: false + 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. + min_version: 2.26 type_1: description: | Filters the response by an image type. For example, ``snapshot`` or ``backup``. @@ -500,7 +581,7 @@ OS-DCF:diskConfig: in: body required: false type: string -OS-DCF:diskConfig_1: +disk_config: description: | Disk configuration. The value is either: @@ -597,11 +678,25 @@ accessIPv4: required: true type: string description: | - IPv4 address that should be used to access this server. + IPv4 address that should be used to access this server. May be + automatically set by the provider. accessIPv6: in: body required: true type: string + description: | + IPv6 address that should be used to access this server. May be + automatically set by the provider. +accessIPv4_in: + in: body + required: false + type: string + description: | + IPv4 address that should be used to access this server. +accessIPv6_in: + in: body + required: false + type: string description: | IPv6 address that should be used to access this server. addFixedIp: @@ -761,6 +856,12 @@ config_drive: in: body required: false type: boolean +config_drive_resp: + description: | + Indicates whether or not a config drive was used for this server. + in: body + required: true + type: boolean confirmResize: description: | The action. @@ -1257,7 +1358,7 @@ key_name: in: body required: false type: string -key_name_1: +key_name_resp: description: | The name of associated key pair, if any. in: body @@ -1346,10 +1447,10 @@ metadata_1: in: body required: false type: object -metadata_2: +metadata_compat: description: | A dictionary of metadata key-and-value pairs, which is maintained for backward - compatibility. The API always returns an empty metadata dictionary. + compatibility. in: body required: true type: object @@ -1428,6 +1529,15 @@ server_name: in: body required: true type: string +server_description: + type: string + in: body + required: false + min_version: 2.19 + description: | + A free form description of the server. Limited to 255 characters + in length. Before microversion 2.19 this was set to the server + name. name_8: description: | Name of the extension. @@ -2000,6 +2110,12 @@ tag: in: body required: false type: string +tenant_id_body: + description: | + The UUID of the tenant this server is owned by. + in: body + required: true + type: string to_port: description: | The port at end of range. diff --git a/api-ref/source/servers.inc b/api-ref/source/servers.inc index ab67868f656e..ea92548a25ad 100644 --- a/api-ref/source/servers.inc +++ b/api-ref/source/servers.inc @@ -1,5 +1,6 @@ .. -*- rst -*- -.. needs:parameter_verification +.. TODO(sdague) parameter microversions need to be gone through in the + response (request side should be good) .. needs:example_verification .. needs:body_verification @@ -156,14 +157,24 @@ Request .. rest_parameters:: parameters.yaml - tenant_id: tenant_id - - changes-since: changes-since + - limit: limit + - marker: marker + - sort_key: sort_key + - sort_dir: sort_dir + - changes-since: changes_since_server - image: image_query - flavor: flavor_query - name: server_name_query - status: server_status_query - - host: host_query - - limit: limit - - marker: marker + - ip: ip_query + - reservation_id: reservation_id_query + - all_tenants: all_tenants_query + - deleted: deleted_query + - ip6: ip6_query + - tags: tags_query + - tags-any: tags_any_query + - not-tags: not_tags_query + - not-tags-any: not_tags_any_query Response -------- @@ -273,6 +284,9 @@ Request - imageRef: imageRef - security_groups: security_groups - metadata: metadata + - accessIPv4: accessIPv4_in + - accessIPv6: accessIPv6_in + - adminPass: adminPass - user_data: user_data - os-availability-zone:availability_zone: os-availability-zone:availability_zone - networks: networks @@ -291,6 +305,7 @@ Request - key_name: key_name - os:scheduler_hints: os:scheduler_hints - OS-DCF:diskConfig: OS-DCF:diskConfig + - description: server_description **Example Create Server: JSON request** @@ -303,15 +318,42 @@ Response .. rest_parameters:: parameters.yaml - server: server - - adminPass: adminPass + - addresses: addresses + - created: created + - flavor: flavor + - hostId: hostId - id: server_id + - image: image + - key_name: key_name_resp - links: links - - OS-DCF:diskConfig: OS-DCF:diskConfig - - security_groups: security_groups + - metadata: metadata_compat + - name: server_name + - accessIPv4: accessIPv4 + - accessIPv6: accessIPv6 + - config_drive: config_drive_resp + - OS-DCF:diskConfig: disk_config + - OS-EXT-AZ:availability_zone: OS-EXT-AZ:availability_zone + - OS-EXT-SRV-ATTR:host: OS-EXT-SRV-ATTR:host + - OS-EXT-SRV-ATTR:hypervisor_hostname: OS-EXT-SRV-ATTR:hypervisor_hostname + - OS-EXT-SRV-ATTR:instance_name: OS-EXT-SRV-ATTR:instance_name + - OS-EXT-STS:power_state: OS-EXT-STS:power_state + - OS-EXT-STS:task_state: OS-EXT-STS:task_state + - OS-EXT-STS:vm_state: OS-EXT-STS:vm_state + - os-extended-volumes:volumes_attached: os-extended-volumes:volumes_attached + - OS-SRV-USG:launched_at: OS-SRV-USG:launched_at + - OS-SRV-USG:terminated_at: OS-SRV-USG:terminated_at + - progress: progress + - security_groups: security_groups_obj + - security_group.name: name + - status: server_status + - host_status: host_status + - tenant_id: tenant_id_body + - updated: updated + - user_id: user_id **Example Create Server: JSON response** -.. literalinclude:: ../../doc/api_samples/servers/server-create-resp.json +.. literalinclude:: ../../doc/api_samples/all_extensions/server-create-resp.json :language: javascript @@ -346,14 +388,24 @@ Request .. rest_parameters:: parameters.yaml - tenant_id: tenant_id - - changes-since: changes-since + - limit: limit + - marker: marker + - sort_key: sort_key + - sort_dir: sort_dir + - changes-since: changes_since_server - image: image_query - flavor: flavor_query - name: server_name_query - status: server_status_query - - host: host_query - - limit: limit - - marker: marker + - ip: ip_query + - reservation_id: reservation_id_query + - all_tenants: all_tenants_query + - deleted: deleted_query + - ip6: ip6_query + - tags: tags_query + - tags-any: tags_any_query + - not-tags: not_tags_query + - not-tags-any: not_tags_any_query Response -------- @@ -367,11 +419,14 @@ Response - hostId: hostId - id: server_id - image: image - - key_name: key_name + - key_name: key_name_resp - links: links - - metadata: metadata - - name: name - - OS-DCF:diskConfig: OS-DCF:diskConfig + - metadata: metadata_compat + - name: server_name + - accessIPv4: accessIPv4 + - accessIPv6: accessIPv6 + - config_drive: config_drive_resp + - OS-DCF:diskConfig: disk_config - OS-EXT-AZ:availability_zone: OS-EXT-AZ:availability_zone - OS-EXT-SRV-ATTR:host: OS-EXT-SRV-ATTR:host - OS-EXT-SRV-ATTR:hypervisor_hostname: OS-EXT-SRV-ATTR:hypervisor_hostname @@ -384,19 +439,16 @@ Response - OS-SRV-USG:terminated_at: OS-SRV-USG:terminated_at - progress: progress - security_groups: security_groups_obj - - security_group.description: description - - security_group.id: id - security_group.name: name - - security_group.rules: rules - status: server_status - host_status: host_status - - tenant_id: tenant_id + - tenant_id: tenant_id_body - updated: updated - user_id: user_id **Example List Servers Detailed: JSON response** -.. literalinclude:: /../../doc/api_samples/servers/servers-details-resp.json +.. literalinclude:: /../../doc/api_samples/all_extensions/servers-details-resp.json :language: javascript @@ -446,11 +498,14 @@ Response - hostId: hostId - id: server_id - image: image - - key_name: key_name + - key_name: key_name_resp - links: links - - metadata: metadata + - metadata: metadata_compat - name: server_name - - OS-DCF:diskConfig: OS-DCF:diskConfig + - accessIPv4: accessIPv4 + - accessIPv6: accessIPv6 + - config_drive: config_drive_resp + - OS-DCF:diskConfig: disk_config - OS-EXT-AZ:availability_zone: OS-EXT-AZ:availability_zone - OS-EXT-SRV-ATTR:host: OS-EXT-SRV-ATTR:host - OS-EXT-SRV-ATTR:hypervisor_hostname: OS-EXT-SRV-ATTR:hypervisor_hostname @@ -463,19 +518,16 @@ Response - OS-SRV-USG:terminated_at: OS-SRV-USG:terminated_at - progress: progress - security_groups: security_groups_obj - - security_group.description: description - - security_group.id: id - security_group.name: name - - security_group.rules: rules - status: server_status - host_status: host_status - - tenant_id: tenant_id + - tenant_id: tenant_id_body - updated: updated - user_id: user_id **Example Show Server Details: JSON response** -.. literalinclude:: ../../doc/api_samples/servers/server-get-resp.json +.. literalinclude:: ../../doc/api_samples/all_extensions/server-get-resp.json :language: javascript Update Server @@ -483,13 +535,7 @@ Update Server .. rest_method:: PUT /v2.1/{tenant_id}/servers/{server_id} -Updates the editable attributes of a server. - -Preconditions - -The server must exist. - -You can edit the ``accessIPv4``, ``accessIPv6``, ``diskConfig`` and ``name`` attributes. +Updates the editable attributes of an existing server. Normal response codes: 200 @@ -503,10 +549,11 @@ Request - tenant_id: tenant_id - server_id: server_id_path - - accessIPv4: accessIPv4 - - accessIPv6: accessIPv6 + - accessIPv4: accessIPv4_in + - accessIPv6: accessIPv6_in - name: server_name - OS-DCF:diskConfig: OS-DCF:diskConfig + - description: server_description **Example Update server name: JSON request** @@ -542,7 +589,9 @@ Response - key_name: key_name - links: links - metadata: metadata - - name: name + - name: server_name + - accessIPv4: accessIPv4 + - accessIPv6: accessIPv6 - OS-DCF:diskConfig: OS-DCF:diskConfig - OS-EXT-AZ:availability_zone: OS-EXT-AZ:availability_zone - OS-EXT-SRV-ATTR:host: OS-EXT-SRV-ATTR:host @@ -556,10 +605,7 @@ Response - OS-SRV-USG:terminated_at: OS-SRV-USG:terminated_at - progress: progress - security_groups: security_groups_obj - - security_group.description: description - - security_group.id: id - security_group.name: name - - security_group.rules: rules - status: server_status - host_status: host_status - tenant_id: tenant_id