openstack/watcher
Code Issues Proposed changes
f7dcefb554
watcher/api-ref/source/watcher-api-v1-audits.inc
Alexander Chadin c4a30153f1 API Microversioning 
This patch set adds API microversion support along
with the first API microversion: start/end time for
CONTINUOUS audits.

APIImpact

Implements: blueprint api-microversioning
Depends-On: I6bb838d777b2c7aa799a70485980e5dc87838456
Change-Id: I17309d80b637f02bc5e6d33294472e02add88f86
2018-10-29 08:45:32 +00:00

363 lines
7.6 KiB
ReStructuredText
Raw Blame History

.. -*- 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.
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
- start_time: audit_starttime
- end_time: audit_endtime
**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
- hostname: audit_hostname
- start_time: audit_starttime
- end_time: audit_endtime
**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
- hostname: audit_hostname
- start_time: audit_starttime
- end_time: audit_endtime
**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
- hostname: audit_hostname
- start_time: audit_starttime
- end_time: audit_endtime
**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
- hostname: audit_hostname
- start_time: audit_starttime
- end_time: audit_endtime
**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
- hostname: audit_hostname
- start_time: audit_starttime
- end_time: audit_endtime
**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
View Git Blame Copy Permalink