Add API Reference for Watcher
This patch set adds API Reference along with some fixes to documentation. It partially fixes bug #1757423. Change-Id: I107b4fd5daf40aad63fc13864debbbbc82a9826c
This commit is contained in:
Alexander Chadin
349
api-ref/source/watcher-api-v1-audits.inc
Normal file
349
api-ref/source/watcher-api-v1-audits.inc
Normal file
@@ -0,0 +1,349 @@
|
||||
.. -*- rst -*-
|
||||
|
||||
======
|
||||
Audits
|
||||
======
|
||||
|
||||
There are creating, listing, updating and deleting methods of Watcher Audit
|
||||
resources which are implemented via the ``/v1/audits`` resource.
|
||||
|
||||
In the Watcher system, an ``Audit`` is a request for optimizing a ``Cluster``.
|
||||
|
||||
The optimization is done in order to satisfy one ``Goal`` on a given
|
||||
``Cluster``.
|
||||
|
||||
For each ``Audit``, the Watcher system generates an ``Action Plan``.
|
||||
|
||||
Create Audit
|
||||
============
|
||||
|
||||
.. rest_method:: POST /v1/audits
|
||||
|
||||
Creates a new Audit resource.
|
||||
|
||||
Mandatory attribute to be supplied: ``audit_type``.
|
||||
|
||||
``Audit`` can be created either based on existed ``Audit Template`` or by
|
||||
itself. In the first case, there also should be supplied
|
||||
``audit_template_uuid``. If ``Audit`` is created without ``Audit Template``,
|
||||
``goal`` should be provided.
|
||||
|
||||
.. warning::
|
||||
**Only ``audit_template_uuid`` can be used to create audit so far.**
|
||||
It should be fixed during the ``Rocky`` cycle.
|
||||
|
||||
Normal response codes: 201
|
||||
|
||||
Error codes: 400,404
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- audit_template_uuid: audittemplate_name
|
||||
- audit_type: audit_type
|
||||
- name: audit_name
|
||||
- goal: audit_goal
|
||||
- strategy: audit_strategy
|
||||
- parameters: audit_parameters
|
||||
- interval: audit_interval
|
||||
- scope: audittemplate_scope
|
||||
- auto_trigger: audit_autotrigger
|
||||
|
||||
**Example ONESHOT Audit creation request:**
|
||||
|
||||
.. literalinclude:: samples/audit-create-request-oneshot.json
|
||||
:language: javascript
|
||||
|
||||
**Example CONTINUOUS Audit creation request with a specified strategy:**
|
||||
|
||||
.. literalinclude:: samples/audit-create-request-continuous.json
|
||||
:language: javascript
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
The list and example below are representative of the response as of API
|
||||
version 1:
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- uuid: uuid
|
||||
- name: audit_name
|
||||
- audit_type: audit_type
|
||||
- strategy_uuid: strategy_uuid
|
||||
- strategy_name: strategy_name
|
||||
- goal_uuid: goal_uuid
|
||||
- goal_name: goal_name
|
||||
- interval: audit_interval
|
||||
- next_run_time: audit_next_run_time
|
||||
- parameters: audit_parameters
|
||||
- auto_trigger: audit_autotrigger
|
||||
- state: audit_state
|
||||
- scope: audittemplate_scope
|
||||
- links: links
|
||||
|
||||
**Example JSON representation of an Audit:**
|
||||
|
||||
.. literalinclude:: samples/audit-create-response.json
|
||||
:language: javascript
|
||||
|
||||
List Audit
|
||||
==========
|
||||
|
||||
.. rest_method:: GET /v1/audits
|
||||
|
||||
Returns a list of Audit resources.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error codes: 400,401
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- goal: r_goal
|
||||
- strategy: r_strategy
|
||||
- limit: limit
|
||||
- marker: marker
|
||||
- sort_dir: sort_dir
|
||||
- sort_key: sort_key
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- uuid: uuid
|
||||
- name: audit_name
|
||||
- audit_type: audit_type
|
||||
- strategy_uuid: strategy_uuid
|
||||
- strategy_name: strategy_name
|
||||
- goal_uuid: goal_uuid
|
||||
- goal_name: goal_name
|
||||
- interval: audit_interval
|
||||
- next_run_time: audit_next_run_time
|
||||
- auto_trigger: audit_autotrigger
|
||||
- state: audit_state
|
||||
- scope: audittemplate_scope
|
||||
- links: links
|
||||
|
||||
**Example JSON representation of an Audit:**
|
||||
|
||||
.. literalinclude:: samples/audit-list-response.json
|
||||
:language: javascript
|
||||
|
||||
List Audit Detailed
|
||||
===================
|
||||
|
||||
.. rest_method:: GET /v1/audits/detail
|
||||
|
||||
Returns a list of Audit resources with complete details.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error codes: 400,401
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- goal: r_goal
|
||||
- strategy: r_strategy
|
||||
- limit: limit
|
||||
- marker: marker
|
||||
- sort_dir: sort_dir
|
||||
- sort_key: sort_key
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- uuid: uuid
|
||||
- name: audit_name
|
||||
- audit_type: audit_type
|
||||
- strategy_uuid: strategy_uuid
|
||||
- strategy_name: strategy_name
|
||||
- goal_uuid: goal_uuid
|
||||
- goal_name: goal_name
|
||||
- interval: audit_interval
|
||||
- next_run_time: audit_next_run_time
|
||||
- parameters: audit_parameters
|
||||
- auto_trigger: audit_autotrigger
|
||||
- state: audit_state
|
||||
- scope: audittemplate_scope
|
||||
- links: links
|
||||
|
||||
**Example JSON representation of an Audit:**
|
||||
|
||||
.. literalinclude:: samples/audit-list-detailed-response.json
|
||||
:language: javascript
|
||||
|
||||
Show Audit
|
||||
==========
|
||||
|
||||
.. rest_method:: GET /v1/audits/{audit_ident}
|
||||
|
||||
Shows details for an Audit.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error codes: 404
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- audit_ident: audit_ident
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- uuid: uuid
|
||||
- name: audit_name
|
||||
- audit_type: audit_type
|
||||
- strategy_uuid: strategy_uuid
|
||||
- strategy_name: strategy_name
|
||||
- goal_uuid: goal_uuid
|
||||
- goal_name: goal_name
|
||||
- interval: audit_interval
|
||||
- next_run_time: audit_next_run_time
|
||||
- parameters: audit_parameters
|
||||
- auto_trigger: audit_autotrigger
|
||||
- state: audit_state
|
||||
- scope: audittemplate_scope
|
||||
- links: links
|
||||
|
||||
**Example JSON representation of an Audit:**
|
||||
|
||||
.. literalinclude:: samples/audit-show-response.json
|
||||
:language: javascript
|
||||
|
||||
Cancel Audit
|
||||
============
|
||||
|
||||
.. rest_method:: PATCH /v1/audits/{audit_ident}
|
||||
|
||||
Cancels an ONGOING Audit resource.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error codes: 400,404
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- audit_ident: audit_ident
|
||||
|
||||
**Example Audit cancelling request:**
|
||||
|
||||
.. literalinclude:: samples/audit-cancel-request.json
|
||||
:language: javascript
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
The list and example below are representative of the response as of API
|
||||
version 1:
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- uuid: uuid
|
||||
- name: audit_name
|
||||
- audit_type: audit_type
|
||||
- strategy_uuid: strategy_uuid
|
||||
- strategy_name: strategy_name
|
||||
- goal_uuid: goal_uuid
|
||||
- goal_name: goal_name
|
||||
- interval: audit_interval
|
||||
- next_run_time: audit_next_run_time
|
||||
- parameters: audit_parameters
|
||||
- auto_trigger: audit_autotrigger
|
||||
- state: audit_state
|
||||
- scope: audittemplate_scope
|
||||
- links: links
|
||||
|
||||
**Example JSON representation of an Audit:**
|
||||
|
||||
.. literalinclude:: samples/audit-cancel-response.json
|
||||
:language: javascript
|
||||
|
||||
Update Audit
|
||||
============
|
||||
|
||||
.. rest_method:: PATCH /v1/audits/{audit_ident}
|
||||
|
||||
Updates an Audit with the given information.
|
||||
|
||||
.. note:
|
||||
``audit_type`` shouldn't be changed by PATCH method.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error codes: 400,404
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- audit_ident: audit_ident
|
||||
|
||||
**Example PATCH document updating Audit:**
|
||||
|
||||
.. literalinclude:: samples/audit-update-request.json
|
||||
:language: javascript
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- uuid: uuid
|
||||
- name: audit_name
|
||||
- audit_type: audit_type
|
||||
- strategy_uuid: strategy_uuid
|
||||
- strategy_name: strategy_name
|
||||
- goal_uuid: goal_uuid
|
||||
- goal_name: goal_name
|
||||
- interval: audit_interval
|
||||
- next_run_time: audit_next_run_time
|
||||
- parameters: audit_parameters
|
||||
- auto_trigger: audit_autotrigger
|
||||
- state: audit_state
|
||||
- scope: audittemplate_scope
|
||||
- links: links
|
||||
|
||||
**Example JSON representation of an Audit:**
|
||||
|
||||
.. literalinclude:: samples/audit-update-response.json
|
||||
:language: javascript
|
||||
|
||||
Delete Audit
|
||||
============
|
||||
|
||||
.. rest_method:: DELETE /v1/audits/{audit_ident}
|
||||
|
||||
Deletes an Audit. Audit can be deleted only from FAILED, SUCCEEDED, CANCELLED,
|
||||
SUSPENDED states.
|
||||
|
||||
Normal response codes: 204
|
||||
|
||||
Error codes: 404
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- audit_ident: audit_ident
|
||||
Reference in New Issue
Block a user