6cbf3fa7f7
* API Reference and documentation as two seperate sphinx document sets * Information from the Devstack guide and README moved over to the new documentation * Configuration examples * Examples of building plugins * Both use the new sphinx-rtd-theme Change-Id: If347905aa14b77b5943f1a9de97f6e287b98ce95
479 lines
11 KiB
C++
479 lines
11 KiB
C++
*************************
|
|
Administrative Endpoints
|
|
*************************
|
|
|
|
Endpoints for the management of tasks, tokens, and notifications. Most of
|
|
these are limited by roles, or are for admin use only.
|
|
|
|
Status
|
|
=======
|
|
.. rest_method:: GET /v1/status
|
|
|
|
Authentication: Administrator
|
|
|
|
Normal Response Code: 200
|
|
|
|
Simple status endpoint.
|
|
|
|
Returns a list of unacknowledged error notifications,
|
|
and both the last created and last completed tasks.
|
|
|
|
|
|
List Tasks
|
|
===========
|
|
.. rest_method:: GET /v1/tasks
|
|
|
|
Authentication: Administrator
|
|
|
|
Normal Response Codes: 200
|
|
|
|
Error Response Codes: 401, 403
|
|
|
|
Lists all tasks.
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- filters: filters
|
|
- page: page
|
|
- tasks_per_page: tasks_per_page
|
|
|
|
Request Example
|
|
-----------------
|
|
|
|
.. code-block:: bash
|
|
|
|
curl -H "X-Auth-Token: $OS_TOKEN" http://adjutant/v1/tasks
|
|
|
|
Response Example
|
|
------------------
|
|
.. code-block:: javascript
|
|
|
|
{
|
|
"tasks": [
|
|
{
|
|
"action_notes": {
|
|
"ResetUserPasswordAction": [
|
|
"Existing user with matching email.",
|
|
]
|
|
},
|
|
"actions": [
|
|
{
|
|
"action_name": "ResetUserPasswordAction",
|
|
"data": {
|
|
"domain_name": "Default",
|
|
"email": "demo@example.com"
|
|
},
|
|
"valid": true
|
|
}
|
|
],
|
|
"approved": true,
|
|
"approved_by": {},
|
|
"approved_on": "2017-08-30T21:29:48.484441Z",
|
|
"cancelled": false,
|
|
"completed": true,
|
|
"completed_on": "2017-08-30T21:30:13.269498Z",
|
|
"created_on": "2017-08-30T21:29:47.989851Z",
|
|
"ip_address": "127.0.0.1",
|
|
"keystone_user": {},
|
|
"project_id": null,
|
|
"task_type": "reset_password",
|
|
"uuid": "d5c7901cfecd45ec9a87871035c9f662"
|
|
},
|
|
{
|
|
"action_notes": {
|
|
"NewProjectDefaultNetworkAction": [],
|
|
"NewProjectWithUserAction": [],
|
|
"SetProjectQuotaAction": []
|
|
},
|
|
"actions": [
|
|
{
|
|
"action_name": "NewProjectWithUserAction",
|
|
"data": {
|
|
"domain_id": "default",
|
|
"email": "test@example.com",
|
|
"parent_id": null,
|
|
"project_name": "test_project"
|
|
},
|
|
"valid": true
|
|
},
|
|
{
|
|
"action_name": "NewProjectDefaultNetworkAction",
|
|
"data": {
|
|
"region": "RegionOne",
|
|
"setup_network": false
|
|
},
|
|
"valid": true
|
|
},
|
|
{
|
|
"action_name": "SetProjectQuotaAction",
|
|
"data": {},
|
|
"valid": true
|
|
}
|
|
],
|
|
"approved": false,
|
|
"approved_by": {},
|
|
"approved_on": None,
|
|
"cancelled": false,
|
|
"completed": false,
|
|
"completed_on": null,
|
|
"created_on": "2017-07-26T21:44:21.082248Z",
|
|
"ip_address": "127.0.0.1",
|
|
"keystone_user": {},
|
|
"project_id": null,
|
|
"task_type": "signup",
|
|
"uuid": "370d952c63ba410c8704abc12cfd97b7"
|
|
}
|
|
}
|
|
|
|
Task Details
|
|
=============
|
|
.. rest_method:: GET /v1/tasks/<task_id>
|
|
|
|
Authentication: Administrator
|
|
|
|
Normal Response Codes: 200
|
|
|
|
Error Response Codes: 401, 403, 404
|
|
|
|
Gives details for the specific task.
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- task_id: task_id
|
|
|
|
Request Example
|
|
----------------
|
|
|
|
.. code-block:: bash
|
|
|
|
curl -H "X-Auth-Token: $OS_TOKEN" http://adjutant/v1/tasks/d5c7901cfecd45ec9a87871035c9f662
|
|
|
|
Response Example
|
|
-----------------
|
|
.. code-block:: javascript
|
|
|
|
{
|
|
"action_notes": {
|
|
"ResetUserPasswordAction": [
|
|
"Existing user with matching email.",
|
|
]
|
|
},
|
|
"actions": [
|
|
{
|
|
"action_name": "ResetUserPasswordAction",
|
|
"data": {
|
|
"domain_name": "Default",
|
|
"email": "demo@example.com"
|
|
},
|
|
"valid": true
|
|
}
|
|
],
|
|
"approved": true,
|
|
"approved_by": {},
|
|
"approved_on": "2017-08-30T21:29:48.484441Z",
|
|
"cancelled": false,
|
|
"completed": true,
|
|
"completed_on": null,
|
|
"created_on": "2017-08-30T21:29:47.989851Z",
|
|
"ip_address": "127.0.0.1",
|
|
"keystone_user": {},
|
|
"project_id": null,
|
|
"task_type": "reset_password",
|
|
"uuid": "d5c7901cfecd45ec9a87871035c9f662"
|
|
}
|
|
|
|
|
|
Update Task
|
|
============
|
|
.. rest_method:: PUT /v1/tasks/<task_id>
|
|
|
|
Authentication: Project Admin or Project Moderator
|
|
|
|
Normal Response Codes: 200
|
|
|
|
Error Response Codes: 400, 401, 403, 404
|
|
|
|
Replace the data in an unapproved action and rerun the preapproval steps
|
|
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- task_data: task_data
|
|
|
|
Request Example
|
|
----------------
|
|
|
|
.. code-block:: bash
|
|
|
|
curl -H "X-Auth-Token: $OS_TOKEN" \
|
|
-H 'Content-Type: application/json' \
|
|
-X PUT --data '{
|
|
"project_name": "a_project",
|
|
"email": "example.a@t.com",
|
|
"region": "RegionOne",
|
|
"setup_network": false
|
|
}' http://0.0.0.0:5050/v1/tasks/19dbe418ecc14aeb94053f23eda01c78
|
|
|
|
Response Example
|
|
----------------
|
|
.. code-block:: javascript
|
|
|
|
{
|
|
"notes": ["Task successfully updated."]
|
|
}
|
|
|
|
Approve Task
|
|
============
|
|
.. rest_method:: POST /v1/tasks/<task_id>
|
|
|
|
Authentication: Administrator
|
|
|
|
Normal Response Codes: 200
|
|
|
|
Error Response Codes: 400, 401, 403, 404
|
|
|
|
Approves a task and runs the actions approval steps.
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- task_id: task_id
|
|
- approved: approved
|
|
|
|
Request Example
|
|
----------------
|
|
|
|
.. code-block:: bash
|
|
|
|
curl -H "X-Auth-Token: $OS_TOKEN" -H 'Content-Type: application/json' \
|
|
-d '{"approved": true}' http://0.0.0.0:5050/v1/tasks/19dbe418ecc14aeb94053f23eda01c78
|
|
|
|
Response Example
|
|
-----------------
|
|
.. code-block:: javascript
|
|
|
|
{
|
|
"notes": ["Created Token."]
|
|
}
|
|
|
|
In most cases an email will be sent after approval to the user who requested
|
|
the task.
|
|
|
|
Cancel Task
|
|
===========
|
|
.. rest_method:: DELETE /v1/tasks/<task_id>
|
|
|
|
Authentication: Administrator, Project Admin or Project Moderator
|
|
|
|
Normal Response Codes: 200
|
|
|
|
Error Response Codes: 400, 401, 403, 404
|
|
|
|
Cancel a task. Tasks can be cancelled at any stage prior to their completion,
|
|
an issued token for a cancelled task will be invalidated.
|
|
|
|
Project Admins and Project Moderators can only cancel tasks associated with
|
|
their projects.
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- task_id: task_id
|
|
|
|
List tokens
|
|
============
|
|
.. rest_method:: GET /v1/tokens
|
|
|
|
Authentication: Administrator
|
|
|
|
Normal Response Codes: 200
|
|
|
|
Error Response Codes: 401, 403
|
|
|
|
List all active tokens.
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- filters: filters
|
|
|
|
Reissue Tokens
|
|
===============
|
|
.. rest_method:: POST /v1/tokens
|
|
|
|
Authentication: Administrator, Project Admin or Project Moderator
|
|
|
|
Normal Response Codes: 200
|
|
|
|
Error Response Codes: 400, 401, 403, 404
|
|
|
|
Reissue a token for the specified task.
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- task_id: task_id_body
|
|
|
|
Delete Expired Tokens
|
|
======================
|
|
.. rest_method:: DELETE /v1/token
|
|
|
|
Authentication: Administrator
|
|
|
|
Normal Response Codes: 200
|
|
|
|
Error Response Codes: 401, 403
|
|
|
|
Delete all expired tokens.
|
|
|
|
Note that if a token has expired it will be deleted when someone attempts to
|
|
access it, this will prevent the database from clogging up however will not
|
|
have an effect on functionality.
|
|
|
|
|
|
Get Token Details
|
|
======================
|
|
.. rest_method:: GET /v1/token/<token_id>
|
|
|
|
Authentication: Unauthenticated
|
|
|
|
Normal Response Codes: 200
|
|
|
|
Error Response Codes: 401, 403, 404
|
|
|
|
Details the actions, task_type and required fields of the token
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- token_id: token_id
|
|
|
|
Request Example
|
|
----------------
|
|
.. code-block:: bash
|
|
|
|
curl http://0.0.0.0:5050/v1/tokens/771af33fb28e46aab45e265bd6a6d469
|
|
|
|
Response Example
|
|
-----------------
|
|
.. code-block:: javascript
|
|
|
|
{
|
|
"actions": [
|
|
"NewProjectWithUserAction",
|
|
"NewProjectDefaultNetworkAction",
|
|
"SetProjectQuotaAction"
|
|
],
|
|
"required_fields": [
|
|
"password"
|
|
],
|
|
"task_type": "signup"
|
|
}
|
|
|
|
|
|
Submit Token
|
|
======================
|
|
.. rest_method:: POST /v1/token/<token_id>
|
|
|
|
Authentication: Unauthenticated
|
|
|
|
Normal Response Codes: 200
|
|
|
|
Error Response Codes: 400, 404
|
|
|
|
Submit a token and it's data to the last stage of an action execution.
|
|
A 400 will be return if it does not contain all of the necessary fields.
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- token_id: token_id
|
|
- token_data: token_data
|
|
|
|
Request Example
|
|
------------------
|
|
.. code-block:: bash
|
|
|
|
curl -H 'Content-Type: application/json' \
|
|
-d '{"password": "12345"}' http://0.0.0.0:5050/v1/tokens/771af33fb28e46aab45e265bd6a6d469
|
|
|
|
Response Example
|
|
-----------------
|
|
.. code-block:: javascript
|
|
|
|
{"notes":["Token submitted successfully."]}
|
|
|
|
In most cases an email will be sent after token submission, detailing what
|
|
has changed.
|
|
|
|
List Notifications
|
|
======================
|
|
.. rest_method:: GET /v1/notification
|
|
|
|
Authentication: Administrator
|
|
|
|
Normal Response Codes: 200
|
|
|
|
Error Response Codes: 401, 403
|
|
|
|
List all unacknowledged notifications
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- filters: filters
|
|
|
|
Acknowledge a List of Notifications
|
|
===================================
|
|
.. rest_method:: POST /v1/notification
|
|
|
|
Authentication: Administrator
|
|
|
|
Mark a given list of notifications as acknowledged
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- notifications: notifications
|
|
|
|
Notification Details
|
|
=====================
|
|
.. rest_method:: GET /v1/notification/<notification_id>
|
|
|
|
Get details of a specific notification
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- notification_id: notification_id
|
|
|
|
|
|
Acknowledge Notification
|
|
========================
|
|
.. rest_method:: GET /v1/notification/<notification_id>
|
|
|
|
Acknowledge a specific notification.
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- notification_id: notification_id
|
|
- acknowledged: acknowledged
|
|
|
|
|
|
|
|
Filtering Tasks, Tokens, and Notifications
|
|
==========================================
|
|
The task, token, and notification list endpoints can be filtered using a
|
|
slight variant of the Django ORM filters.
|
|
|
|
This is done but sending a json with filters via HTTP parameters:
|
|
|
|
.. code-block:: javascript
|
|
|
|
{'filters': {'fieldname': { 'operation': 'value'}}
|
|
|
|
|
|
Example:
|
|
|
|
.. code-block:: javascript
|
|
|
|
{'filters': {'task_id': { 'exact': '842433bb-fa08-4fc1-8c3b-aa9904ceb370'}}
|
|
|
|
|
|
This looks a bit messy in the url as that json ends up being url-safe encoded,
|
|
but doing the filters this way gives us a fairly large amount of flexibility.
|
|
|
|
Possible field lookup operations:
|
|
https://docs.djangoproject.com/en/1.11/ref/models/querysets/#id4
|