Merge "api-ref: update parameter validation on servers"

2016-05-10 15:36:47 +00:00 · 2016-05-10 15:36:47 +00:00 · cb0740aa2d
commit cb0740aa2d
parent 2a0fce7a44 e131317430
2 changed files with 213 additions and 51 deletions
--- 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 <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.
--- 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