x/mogan
Code Issues Proposed changes
8d2d165755
mogan/api-ref/source/v1/servers.inc
Xinran 05cc14d399 Pagination support for server list API 
We should support to return a list of servers according to users' requirements.
In this patch, marker, limit, sort_key and sort_dir were added in server list
API.
- marker is used to display a list of servers after marker
- limit is used to determinate the maximum number of servers to display
- sort_key is used to sort the returned server list by specified key value
- sort_dir is used to select a sort direction

DocImpact
APIImpact

Change-Id: Id70e965794c82a0a29e53d4364f65b0f39042c7c
Closes-Bug: #1726665
2017-10-26 07:40:05 +00:00

395 lines
8.5 KiB
ReStructuredText
Raw Blame History

.. -*- rst -*-
===========
Servers
===========
Lists, creates, shows details for, updates, and deletes servers.
Create Server
===============
.. rest_method:: POST /servers
Creates a server.
The progress of this operation depends on the location of the
requested image, network I/O, selected type, and other factors.
The ``Location`` header returns the full URL to the newly created
server and is available as a ``self`` and ``bookmark`` link in the
server representation.
Normal response codes: 201
Error response codes: badRequest(400), unauthorized(401),
forbidden(403), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- server: server
- name: server_name
- description: server_description
- flavor_uuid: flavorRef
- image_uuid: imageRef
- availability_zone: availability_zone
- networks: networks
- networks.net_id: network_uuid
- networks.port_id: port_uuid
- metadata: metadata
- user_data: user_data
- personality: personality
- key_name: key_name
- partitions: partitions
- scheduler_hints: scheduler_hints
**Example Create Server: JSON request**
.. literalinclude:: samples/servers/server-create-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- name: server_name
- description: server_description
- flavor_uuid: flavorRef
- image_uuid: imageRef
- availability_zone: availability_zone
- addresses: addresses
- node: node
- links: links
- uuid: server_uuid
- status: server_status
- power_state: server_power_state
- project_id: project_id_body
- user_id: user_id_body
- updated_at: updated_at
- created_at: created_at
- metadata: metadata
- affinity_zone: affinity_zone
- key_name: key_name
- partitions: partitions
- locked: lock_state
**Example Create Server: JSON response**
.. literalinclude:: samples/servers/server-create-resp.json
:language: javascript
Create Multiple Servers
=========================
.. rest_method:: POST /servers
Create Multiple Servers.
There is a second kind of create call which can create multiple servers
at once. This supports all the same parameters as create with a few additional
attributes specific to multiple create.
Error handling for multiple create is not as consistent as for single server
create, and there is no guarantee that all the servers will be created
successfully.
Normal response codes: 201
Error response codes: badRequest(400), unauthorized(401),
forbidden(403), conflict(409)
Request (Additional Parameters)
-------------------------------
These are the parameters beyond single create that are supported.
.. rest_parameters:: parameters.yaml
- name: multi_server_name_body
- min_count: min_count_body
- max_count: max_count_body
**Example Create Multiple Server: JSON request**
.. literalinclude:: samples/servers/multi-server-create-req.json
:language: javascript
Response
--------
The first server will be returned. The returned parameters is same to creating
a single server's.
**Example Create Multiple Server: JSON response**
.. literalinclude:: samples/servers/server-create-resp.json
:language: javascript
List Servers
===============
.. rest_method:: GET /servers
Return a list of bare metal Servers, with some useful information about each
Server.
By default, this query will return the name, server uuid, server status
and description for each Server.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401),
forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- name: server_name_query
- status: status_query
- flavor_uuid: flavor_query
- flavor_name: flavor_name_query
- image_uuid: image_query
- ip: fixed_ip_query
- limit: limit
- marker: marker
- sort_key: sort_key
- sort_dir: sort_dir
- all_tenants: all_tenants
- fields: fields
Response
--------
.. rest_parameters:: parameters.yaml
- name: server_name
- description: server_description
- uuid: server_uuid
- status: server_status
- power_state: server_power_state
- links: links
**Example List of Servers: JSON response**
.. literalinclude:: samples/servers/server-list-resp.json
:language: javascript
List Servers Detailed
=======================
.. rest_method:: GET /servers/detail
Return a list of bare metal Servers with complete details. We can also apply
filters to show more precisely the servers.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401),
forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- name: server_name_query
- status: status_query
- flavor_uuid: flavor_query
- flavor_name: flavor_name_query
- image_uuid: image_query
- ip: fixed_ip_query
- limit: limit
- marker: marker
- sort_key: sort_key
- sort_dir: sort_dir
- all_tenants: all_tenants
Response
--------
.. rest_parameters:: parameters.yaml
- name: server_name
- description: server_description
- flavor_uuid: flavorRef
- image_uuid: imageRef
- availability_zone: availability_zone
- addresses: addresses
- node: node
- links: links
- uuid: server_uuid
- status: server_status
- power_state: server_power_state
- project_id: project_id_body
- user_id: user_id_body
- updated_at: updated_at
- created_at: created_at
- launched_at: launched_at
- metadata: metadata
- affinity_zone: affinity_zone
- key_name: key_name
- partitions: partitions
- locked: lock_state
**Example Detailed list of Servers: JSON response**
.. literalinclude:: samples/servers/server-list-detail-resp.json
:language: javascript
Show Server Details
=====================
.. rest_method:: GET /servers/{server_uuid}
Shows details of a server. By default, this will return the full
representation of the resource; an optional fields parameter can be supplied to
return only the specified set.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401),
forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_uuid: server_ident
- fields: fields
Response
--------
.. rest_parameters:: parameters.yaml
- name: server_name
- description: server_description
- flavor_uuid: flavorRef
- image_uuid: imageRef
- availability_zone: availability_zone
- addresses: addresses
- node: node
- links: links
- uuid: server_uuid
- status: server_status
- power_state: server_power_state
- fault: server_fault
- project_id: project_id_body
- user_id: user_id_body
- updated_at: updated_at
- created_at: created_at
- launched_at: launched_at
- metadata: metadata
- affinity_zone: affinity_zone
- key_name: key_name
- partitions: partitions
- locked: lock_state
**Example Server Details: JSON response**
.. literalinclude:: samples/servers/server-detail-resp.json
:language: javascript
**Example Server Details With Fault: JSON response**
.. literalinclude:: samples/servers/server-detail-resp-when-error.json
:language: javascript
Update Server
===============
.. rest_method:: PATCH /servers/{server_uuid}
Updates the information stored about a server.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401),
forbidden(403), conflict(409)
Request
-------
The BODY of the PATCH request must be a JSON PATCH document, adhering to
`RFC 6902 <https://tools.ietf.org/html/rfc6902>`_.
.. rest_parameters:: parameters.yaml
- server_uuid: server_ident
**Example Update Server: JSON request**
.. literalinclude:: samples/servers/server-update-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- name: server_name
- description: server_description
- flavor_uuid: flavorRef
- image_uuid: imageRef
- availability_zone: availability_zone
- addresses: addresses
- node: node
- links: links
- uuid: server_uuid
- status: server_status
- power_state: server_power_state
- project_id: project_id_body
- user_id: user_id_body
- updated_at: updated_at
- created_at: created_at
- metadata: metadata
- affinity_zone: affinity_zone
- key_name: key_name
- partitions: partitions
- locked: lock_state
**Example Update Server: JSON response**
.. literalinclude:: samples/servers/server-update-resp.json
:language: javascript
Delete Server
===============
.. rest_method:: DELETE /servers/{server_uuid}
Deletes a server.
Preconditions
- The server must exist.
Normal response codes: 204
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- server_uuid: server_ident
Response
--------
No body content is returned on a successful DELETE.
View Git Blame Copy Permalink