Admin Logic Version 1 API reference¶

This is the reference for Adjutant when it is using the default configuration. Different deployments may exclude certain DelegateAPIs or include their own additional ones.

The core functionality of Adjutant is built around the concept of tasks and actions.

Actions are both concepts in the database and code that can execute whatever logic is necessary at each stage.

Tasks can bundle a number of actions and have 3 main steps.

A user submits a request to the specified endpoint.
An admin approves the request, or it is automatically approved. At this point the admin can also update invalid data inside the task.
If necessary a user will be emailed a token and will submit additional data (ie passwords or a confirmation) to finish the task.

Depending on the task and the data provided some steps may be skipped.

Authentication¶

The ‘X-Auth-Token’ header value should be provided for authentication with a valid Keystone token.

HTTP Status Codes¶

Success¶

Code	Reason
`200 - OK`	Request was successful.
`200 - OK`	Request successful, task submitted.
`202 - Accepted`	Request is accepted, but processing may take some time.

Error¶

Code	Reason
`400 - Bad Request`	Bad request
`401 - Unauthorized`	User is unauthenticated, or X-Auth-Token has expired.
`403 - Forbidden`	User has the wrong roles for this operation.
`404 - Not Found`	The requested resource could not be found.
`405 - Method Not Allowed`	Method is not valid for this endpoint and resource.
`409 - Conflict`	Conflict
`500 - Internal Server Error`	Something went wrong with the service which prevents it from fulfilling the request.
`503 - Service Unavailable`	Adjutant cannot connect to the Keystone Authentication Server.

Service Discovery¶

GET

Version Discovery Endpoint

Unauthenticated.

JSON containing details of the currently available versions (just v1 for now)

Normal response code: 200

GET

/v1

Version One Details Endpoint

Unauthenticated.

Details V1 version details.

Normal response code: 200

Administrative Endpoints¶

Endpoints for the management of tasks, tokens, and notifications. Most of these are limited by roles, or are for admin use only.

GET

/v1/status

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.

GET

/v1/tasks

List Tasks

Authentication: Administrator

Normal Response Codes: 200

Error Response Codes: 401, 403

Lists all tasks.

Name	In	Type	Description
filters (Optional)	query	dictionary	Django style filters for task, token and notification endpoints. See section Filters for details.
page (Optional)	query	int	Page number to access, starts at and defaults to 1.
tasks_per_page (Optional)	query	int	Limit on the tasks viewed on each page.

Request Example¶

curl -H "X-Auth-Token: $OS_TOKEN" http://adjutant/v1/tasks

Response Example¶

{
    "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_user_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": "create_project_and_user",
        "uuid": "370d952c63ba410c8704abc12cfd97b7"
    }
}

GET

/v1/tasks/

Task Details

Authentication: Administrator

Normal Response Codes: 200

Error Response Codes: 401, 403, 404

Gives details for the specific task.

Name	In	Type	Description
task_id	path	string	The task UUID as given in the task list and email correspondence.

Request Example¶

curl -H "X-Auth-Token: $OS_TOKEN" http://adjutant/v1/tasks/d5c7901cfecd45ec9a87871035c9f662

Response Example¶

{
    "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_user_password",
    "uuid": "d5c7901cfecd45ec9a87871035c9f662"
}

PUT

/v1/tasks/

Update Task

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

Name	In	Type	Description
task_data	body	dictionary	A dictionary replacing all the data for a task. See the task details for what values should be included

Request Example¶

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¶

{
  "notes": ["Task successfully updated."]
}

POST

/v1/tasks/

Approve Task

Authentication: Administrator

Normal Response Codes: 200

Error Response Codes: 400, 401, 403, 404

Approves a task and runs the actions approval steps.

Name	In	Type	Description
task_id	path	string	The task UUID as given in the task list and email correspondence.
approved	body	boolean	Confirmation to approve a task.

Request Example¶

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¶

{
  "notes": ["Created Token."]
}

In most cases an email will be sent after approval to the user who requested the task.

DELETE

/v1/tasks/

Cancel Task

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.

Name	In	Type	Description
task_id	path	string	The task UUID as given in the task list and email correspondence.

GET

/v1/tokens

List tokens

Authentication: Administrator

Normal Response Codes: 200

Error Response Codes: 401, 403

List all active tokens.

Name	In	Type	Description
filters (Optional)	query	dictionary	Django style filters for task, token and notification endpoints. See section Filters for details.

POST

/v1/tokens

Reissue 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.

Name	In	Type	Description
task_id	body	int	The task UUID as given in the task list and email correspondence.

DELETE

/v1/token

Delete Expired Tokens

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

/v1/token/

Get Token Details

Authentication: Unauthenticated

Normal Response Codes: 200

Error Response Codes: 401, 403, 404

Details the actions, task_type and required fields of the token

Name	In	Type	Description
token_id	path	string	The token UUID, as given on the lists and in email correspondence.

Request Example¶

curl http://0.0.0.0:5050/v1/tokens/771af33fb28e46aab45e265bd6a6d469

Response Example¶

{
  "actions": [
      "NewProjectWithUserAction",
      "NewProjectDefaultNetworkAction",
      "SetProjectQuotaAction"
  ],
  "required_fields": [
      "password"
  ],
  "task_type": "create_project_and_user"
}

POST

/v1/token/

Submit 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.

Name	In	Type	Description
token_id	path	string	The token UUID, as given on the lists and in email correspondence.
token_data	body	dictionary	A dictionary replacing all the data for a task. Use the token get request to see what should needs to be included.

Request Example¶

curl -H 'Content-Type: application/json' \
     -d '{"password": "12345"}' http://0.0.0.0:5050/v1/tokens/771af33fb28e46aab45e265bd6a6d469

Response Example¶

{"notes":["Token submitted successfully."]}

In most cases an email will be sent after token submission, detailing what has changed.

GET

/v1/notification

List Notifications

Authentication: Administrator

Normal Response Codes: 200

Error Response Codes: 401, 403

List all unacknowledged notifications

Name	In	Type	Description
filters (Optional)	query	dictionary	Django style filters for task, token and notification endpoints. See section Filters for details.

POST

/v1/notification

Acknowledge a List of Notifications

Authentication: Administrator

Mark a given list of notifications as acknowledged

Name	In	Type	Description
notifications	body	array	List of notification UUIDs to acknowledge

GET

/v1/notification/

Notification Details

Get details of a specific notification

Name	In	Type	Description
notification_id	path	string	The notification UUID, as given on list endpoints and in email correspondence.

GET

/v1/notification/

Acknowledge Notification

Acknowledge a specific notification.

Name	In	Type	Description
notification_id	path	string	The notification UUID, as given on list endpoints and in email correspondence.
acknowledged	body	boolean	Confirmation for acknowledging a notification.

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:

{'filters': {'fieldname': { 'operation': 'value'}}

Example:

{'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

OpenStack Style DelegateAPI Endpoints¶

A response of ‘task created’ means that the task requires admin approval and a response of ‘created token’ indicates that the task has been auto-approved and awaits the submission of an emailed token.

GET

/v1/openstack/users

List users

Authentication: Project Moderator or Admin

List current and pending users in the current project.

Request Example¶

curl -H "X-Auth-Token: $NOS_TOKEN" http://0.0.0.0:5050/v1/openstack/users

Response Example¶

{
    "users": [
        {
            "cohort": "Member",
            "email": "demo@example.com",
            "id": "",
            "manageable": false,
            "name": "demo",
            "roles": [
                "project_admin",
                "_member_"
            ],
            "status": "Active"
        }
    ]
}

POST

/v1/openstack/users

Invite User

Authentication: Project Moderator or Admin

An auto-approved task that will add a user to the project. If the user already exists it will add them directly, otherwise it will create a user when the invitee submits a token sent to them though email

Name	In	Type	Description
roles	body	array	List of roles for the user.
email	body	string	New user email address.
username (Optional)	body	string	New user username, required only if USERNAME_IS_EMAIL is false.

Request Example¶

curl -H "X-Auth-Token: $NOS_TOKEN" http://0.0.0.0:5050/v1/openstack/users \
 -H 'Content-Type: application/json' \
-d '{"roles": ["member"], "email": "new@example.com"}'

Response Example¶

{
  "notes": ["created token"]
}

GET

/v1/openstack/users/

User Details

Authentication: Project Moderator or Admin

Get details on the given user including their roles on your project

Name	In	Type	Description
user_id	path	string	The user id, as seen on the ../v1/openstack/users page. Note that this is the openstack user id for confirmed users and the task ID for invited users.

DELETE

/v1/openstack/users/

Cancel User Invite

Authentication: Project Moderator or Admin

Cancel a pending user invitation. Current users can be removed from your project by removing all of their roles.

Name	In	Type	Description
user_id	path	string	The user id, as seen on the ../v1/openstack/users page. Note that this is the openstack user id for confirmed users and the task ID for invited users.

GET

/v1/openstack/users//roles

List User Roles

Authentication: Project Moderator or Admin

List all roles the user has on the current project

Name	In	Type	Description
user_id	path	string	The user id, as seen on the ../v1/openstack/users page. Note that this is the openstack user id for confirmed users and the task ID for invited users.

PUT

/v1/openstack/users//roles

Add User Roles

Authentication: Project Moderator or Admin

Add the specified roles to the user on the current project.

There is additional authentication in the forms of what roles can be edited by the current user. If the target user has any role not editable by the current user the user will not be able to edit any of their roles. Editiable roles can be found at the List available roles endpoint.

Name	In	Type	Description
user_id	path	string	The user id, as seen on the ../v1/openstack/users page. Note that this is the openstack user id for confirmed users and the task ID for invited users.
roles	body	array	List of roles for the user.

Request Example¶

curl -H "X-Auth-Token: $NOS_TOKEN" -H 'Content-Type: application/json' \
-d '{"roles": ["project_mod"]}' -X PUT \
http://0.0.0.0:5050/v1/openstack/users/5123ca764f3d40d79e3589e91f1ccb8f/roles

Response Example¶

{
    "notes": [
        "Task completed successfully."
    ]
}

DELETE

/v1/openstack/users//roles

Remove User Roles

Authentication: Project Moderator or Admin

Remove the specified roles from the user on the current project.

A project moderator will not be able to change the roles of a project admin.

Name	In	Type	Description
user_id	path	string	The user id, as seen on the ../v1/openstack/users page. Note that this is the openstack user id for confirmed users and the task ID for invited users.
roles	body	array	List of roles for the user.

Request Example¶

curl -H "X-Auth-Token: $NOS_TOKEN" -H 'Content-Type: application/json' \
-d '{"roles": ["project_mod"]}' -X DELETE \
http://0.0.0.0:5050/v1/openstack/users/5123ca764f3d40d79e3589e91f1ccb8f/roles

Response Example¶

{
    "notes": [
        "Task completed successfully."
    ]
}

GET

/v1/openstack/roles

List Available Roles

Authentication: Project Moderator or Admin

List the roles available for the current user to modify.

Request Example¶

curl -H "X-Auth-Token: $NOS_TOKEN" http://0.0.0.0:5050/v1/openstack/roles/

Response Example¶

{
    "roles": [
        {
            "domain_id": null,
            "id": "b81efc1e23a043d0976dc39b3e2727c3",
            "links": {
                "self": "http://identity/v3/roles/b81efc1e23a043d0976dc39b3e2727c3"
            },
            "name": "project_mod"
        },
        {
            "domain_id": null,
            "id": "9fe2ff9ee4384b1894a90878d3e92bab",
            "links": {
                "self": "http://identity/v3/roles/9fe2ff9ee4384b1894a90878d3e92bab"
            },
            "name": "member"
        },
    ]
}

POST

/v1/openstack/users/password-reset

Password Reset

Authentication: Unauthenticated

Unauthenticated for forgotten password requests. If the email has an associated user a token will be sent to them to use to reset their password with.

Name	In	Type	Description
email	body	string	Email address for the user whose password needs resetting
username (Optional)	body	string	Username, required only if USERNAME_IS_EMAIL is false.

Request Example¶

curl -d '{"email": "demo@example.org"}' http://0.0.0.0:5050/v1/openstack/users/password-reset

Response Example¶

{
  "notes": ["If user with email exists, reset token will be issued."]
}

POST

/v1/openstack/email-update

Update Email Address

Authentication: Authenticated

Submit a new email address for the current user. A submission token will be sent to the new address, and a notification to the old email address. The account address will not change until the token submission.

Name	In	Type	Description
email	body	string	New user email address.

Authentication: Unauthenticated

Account creation endpoint.

Name	In	Type	Description
email	body	string	New user email address.
username (Optional)	body	string	New user username, required only if USERNAME_IS_EMAIL is false.
project_name	query	string	Name for the new project.
setup_network	query	boolean	Whether or not to setup a default network for a new project
region	query	string	Region to perform actions in.

Request Example¶

curl -H 'X-Auth-Token: $OS_TOKEN' -H 'Content-Type: application/json' -d '{
    "email": "example@example.com", "project_name": "example_project"}'
    -X POST  http://0.0.0.0:5050/v1/openstack/sign-up

Response Example¶

{
  "notes": ["task created"]
}

GET

/v1/openstack/quotas

Show Quota Details

Authentication: Project Moderator or Admin

List details of the quota for the current project.

Name	In	Type	Description
region	query	string	Region to perform actions in.

Request Example¶

curl -H "X-Auth-Token: $NOS_TOKEN" http://0.0.0.0:5050/v1/openstack/quotas

Response Example¶

{
    "active_quota_tasks": [],
    "quota_size_order": [
        "small",
        "medium",
        "large"
    ],
    "quota_sizes": {
        "large": {
            "cinder": {
                "gigabytes": 50000,
                "snapshots": 600,
                "volumes": 200
            },
            "neutron": {
                "floatingip": 50,
                "network": 10,
                "port": 500,
                ...
            },
            "nova": {
                "cores": 200,
                "fixed_ips": 0,
                "floating_ips": 50,
                "injected_file_content_bytes": 10240,
                ...
            }
        },
        'small': { ... },
        'medium': { ... }
    },
    "regions": [
        {
            "current_quota": {
                "cinder": {
                    "backup_gigabytes": 1000,
                    "backups": 10,
                    "gigabytes": 1000,
                    ...
                },
                "neutron": {
                    "floatingip": 50,
                    "network": 10,
                    "port": 50,
                    ...
                },
                "nova": {
                    "cores": 20,
                    "fixed_ips": -1,
                    "floating_ips": 10,
                    "injected_file_content_bytes": 10240,
                    ...
                }
            },
            "current_quota_size": "custom",
            "current_usage": {
                "cinder": {
                    "gigabytes": 1,
                    "snapshots": 0,
                    "volumes": 1
                },
                "neutron": {
                    "floatingip": 0,
                    "network": 1,
                    "port": 2,
                    "router": 1
                    ...
                },
                "nova": {
                    "cores": 0,
                    "floating_ips": 0,
                    ...
                }
            },
            "quota_change_options": [],
            "region": "RegionOne"
        }
    ]
}

POST

/v1/openstack/quotas

Update Quota

Authentication: Project Moderator or Admin

Starts an update quota task. If regions are not specified it will update the quota across all regions.

Name	In	Type	Description
regions (Optional)	body	array	Regions to perform actions in.
size	body	string	Which size out of the selections shown in the quota get request should the region(s) be updated to.

Request Example¶

curl -H "X-Auth-Token: $NOS_TOKEN" http://0.0.0.0:5050/v1/openstack/quotas
  -d '{"region": "RegionOne", "size": "small"}' -H "Content-Type: application/json"

Response Example¶

{
  "notes": ["Task processed. Awaiting Aprroval."]
}

Additional API Documentation¶

While in debug mode the service will supply online browsable documentation via Django REST Swagger.

This is viewable at: ../docs

Admin Logic Version 1 API reference

Admin Logic Version 1 API reference¶

Authentication¶

HTTP Status Codes¶

Success¶

Error¶

Service Discovery¶

Administrative Endpoints¶

Request Example¶

Response Example¶

Request Example¶

Response Example¶

Request Example¶

Response Example¶

Request Example¶

Response Example¶

Request Example¶

Response Example¶

Request Example¶

Response Example¶

Filtering Tasks, Tokens, and Notifications¶

OpenStack Style DelegateAPI Endpoints¶

Request Example¶

Response Example¶

Request Example¶

Response Example¶

Request Example¶

Response Example¶

Request Example¶

Response Example¶

Request Example¶

Response Example¶

Request Example¶

Response Example¶

Request Example¶

Response Example¶

Request Example¶

Response Example¶

Request Example¶

Response Example¶

Additional API Documentation¶

Adjutant API Reference

Page Contents