************************* 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/ 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/ 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/ 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/ 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/ 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/ 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/ Get details of a specific notification .. rest_parameters:: parameters.yaml - notification_id: notification_id Acknowledge Notification ======================== .. rest_method:: GET /v1/notification/ 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