mogan/api-ref/source/v1/aggregates.inc
Zhenguo Niu a637bfd38a Add aggregate nodes API
* list nodes for the specified aggregates
* add node to an aggregate
* remove node from an aggregate

Change-Id: I78ce523c7ba26860e02dcde84bcb84a6cc0c60ee
2017-07-31 11:03:28 +08:00

271 lines
5.1 KiB
ReStructuredText

.. -*- rst -*-
============
Aggregates
============
Creates and manages node aggregates. An aggregate assigns metadata to
groups of compute nodes. Aggregates are only visible to the cloud provider.
List Aggregates
===============
.. rest_method:: GET /aggregates
Lists all aggregates.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Response
--------
.. rest_parameters:: parameters.yaml
- aggregates: aggregates
- name: aggregate_name
- links: links
- metadata: aggregate_metadata
- uuid: aggregate_uuid
- created_at: created_at
- updated_at: updated_at
**Example List aggregates: JSON response**
.. literalinclude:: samples/aggregates/aggregates-list-resp.json
:language: javascript
Create Aggregate
================
.. rest_method:: POST /aggregates
Creates an aggregate.
Normal response codes: 201
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- name: aggregate_name
- metadata: aggregate_metadata
**Example Create Aggregatei: JSON request**
.. literalinclude:: samples/aggregates/aggregate-create-post-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- name: aggregate_name
- links: links
- metadata: aggregate_metadata
- uuid: aggregate_uuid
- created_at: created_at
- updated_at: updated_at
**Example Create Aggregate: JSON response**
.. literalinclude:: samples/aggregates/aggregate-create-post-resp.json
:language: javascript
Update Aggregate
================
.. rest_method:: PATCH /aggregates/{aggregate_uuid}
Updates an aggregate.
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
- aggregate_uuid: aggregate_uuid_path
**Example Update Aggregate: JSON request**
.. literalinclude:: samples/aggregates/aggregate-update-put-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- name: aggregate_name
- links: links
- metadata: aggregate_metadata
- uuid: aggregate_uuid
- created_at: created_at
- updated_at: updated_at
**Example Update Aggregate: JSON response**
.. literalinclude:: samples/aggregates/aggregate-update-put-resp.json
:language: javascript
Show Aggregate Details
======================
.. rest_method:: GET /aggregates/{aggregate_uuid}
Shows details for an aggregate.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- aggregate_uuid: aggregate_uuid_path
Response
--------
.. rest_parameters:: parameters.yaml
- name: aggregate_name
- links: links
- metadata: aggregate_metadata
- uuid: aggregate_uuid
- created_at: created_at
- updated_at: updated_at
**Example Show Aggregate Details**
.. literalinclude:: samples/aggregates/aggregate-get-resp.json
:language: javascript
Delete Aggregate
================
.. rest_method:: DELETE /aggregates/{aggregate_uuid}
Deletes an aggregate.
Normal response codes: 204
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- aggregate_uuid: aggregate_uuid_path
Response
--------
No body content is returned on a successful DELETE.
List Aggregate Nodes
====================
.. rest_method:: GET /aggregates/{aggregate_uuid}/nodes
Lists nodes for the specified aggregate.
Normal response codes: 200
Error response codes: unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- aggregate_uuid: aggregate_uuid_path
Response
--------
.. rest_parameters:: parameters.yaml
- nodes: aggregate_nodes
**Example List aggregates: JSON response**
.. literalinclude:: samples/aggregates/aggregates-list-nodes-resp.json
:language: javascript
Add Aggregate Node
==================
.. rest_method:: POST /aggregates/{aggregate_uuid}/nodes
Adds a node to an aggregate.
Normal response codes: 204
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- aggregate_uuid: aggregate_uuid_path
- node: aggregate_node
**Example Add Aggregate Node: JSON request**
.. literalinclude:: samples/aggregates/aggregate-add-node-req.json
:language: javascript
Response
--------
If successful, this method does not return content in the response body.
Remove Aggregate Node
=====================
.. rest_method:: DELETE /aggregates/{aggregate_uuid}/nodes/{node}
Removes a node to an aggregate.
Normal response codes: 204
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- aggregate_uuid: aggregate_uuid_path
- node: aggregate_node_path
Response
--------
If successful, this method does not return content in the response body.