openstack/nova
Code Issues Proposed changes

api-ref: update parameter validation on servers

Browse Source 
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
This commit is contained in:
Sean Dague 2016-05-06 08:37:03 -04:00
parent b4db932936
commit e131317430
2 changed files with 213 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
api-ref/source/parameters.yaml
View File

@ -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 <https://en.wikipedia.org/wiki/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.

132
api-ref/source/servers.inc
View File

@ -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