Add first pass of API docs for swift internal API.
This commit is contained in:
rpedde
parent
894f58a1bc
commit
debeb3fd30
463
doc/source/api.rst
Normal file
463
doc/source/api.rst
Normal file
@ -0,0 +1,463 @@
|
|||||||
|
----------
|
||||||
|
Swauth API
|
||||||
|
----------
|
||||||
|
|
||||||
|
Overview
|
||||||
|
========
|
||||||
|
|
||||||
|
Swauth has its own internal versioned REST API for adding, removing,
|
||||||
|
and editing accounts. This document explains the v2 API.
|
||||||
|
|
||||||
|
Authentication
|
||||||
|
--------------
|
||||||
|
|
||||||
|
Each REST request against the swauth API requires the inclusion of a
|
||||||
|
specific authorization user and key to be passed in a specific HTTP
|
||||||
|
header. These headers are defined as ``X-Auth-Admin-User`` and
|
||||||
|
``X-Auth-Admin-Key``.
|
||||||
|
|
||||||
|
Typically, these values are ``.super_admin`` (the site super admin
|
||||||
|
user) with the key being specified in the swauth middleware
|
||||||
|
configuration as ``super_admin_key``.
|
||||||
|
|
||||||
|
This could also be a reseller admin with the appropriate rights to
|
||||||
|
perform actions on reseller accounts.
|
||||||
|
|
||||||
|
Endpoints
|
||||||
|
---------
|
||||||
|
|
||||||
|
The swauth API endpoint is presented on the proxy servers, in the
|
||||||
|
"/auth" namespace. In addition, the API is versioned, and the version
|
||||||
|
documented is version 2. API versions subdivide the auth namespace by
|
||||||
|
version, specified as a version identifier like "v2".
|
||||||
|
|
||||||
|
The auth endpoint described herein is therefore located at "/auth/v2/"
|
||||||
|
as presented by the proxy servers.
|
||||||
|
|
||||||
|
Bear in mind that in order for the auth management API to be
|
||||||
|
presented, it must be enabled in the proxy server config by setting
|
||||||
|
``allow_account_managment`` to ``true`` in the ``[app:proxy-server]``
|
||||||
|
stanza of your proxy-server.conf.
|
||||||
|
|
||||||
|
Responses
|
||||||
|
---------
|
||||||
|
|
||||||
|
Responses from the auth APIs are returned as a JSON structure.
|
||||||
|
Example return values in this document are edited for readability.
|
||||||
|
|
||||||
|
|
||||||
|
Reseller/Admin Services
|
||||||
|
=======================
|
||||||
|
|
||||||
|
Operations can be performed against the endpoint itself to perform
|
||||||
|
general administrative operations. Currently, the only operations
|
||||||
|
that can be performed is a GET operation to get reseller or site admin
|
||||||
|
information.
|
||||||
|
|
||||||
|
Get Admin Info
|
||||||
|
--------------
|
||||||
|
|
||||||
|
A GET request at the swauth endpoint will return reseller information
|
||||||
|
for the account specified in the ``X-Auth-Admin-User`` header.
|
||||||
|
Currently, the information returned is limited to a list of accounts
|
||||||
|
for the reseller or site admin.
|
||||||
|
|
||||||
|
Valid return codes:
|
||||||
|
* 200: Success
|
||||||
|
* 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key
|
||||||
|
* 5xx: Internal error
|
||||||
|
|
||||||
|
Example Request::
|
||||||
|
|
||||||
|
GET /auth/<api version>/ HTTP/1.1
|
||||||
|
X-Auth-Admin-User: .super_user
|
||||||
|
X-Auth-Admin-Key: swauthkey
|
||||||
|
|
||||||
|
Example Curl Request::
|
||||||
|
|
||||||
|
curl -D - https://<endpoint>/auth/v2/ \
|
||||||
|
-H "X-Auth-Admin-User: .super_user" \
|
||||||
|
-H "X-Auth-Admin-Key: swauthkey"
|
||||||
|
|
||||||
|
Example Result::
|
||||||
|
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
|
||||||
|
{ "accounts":
|
||||||
|
[
|
||||||
|
{ "name": "account1" },
|
||||||
|
{ "name": "account2" },
|
||||||
|
{ "name": "account3" }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
Account Services
|
||||||
|
================
|
||||||
|
|
||||||
|
There are API request to get account details, create, and delete
|
||||||
|
accounts, mapping logically to the REST verbs GET, PUT, and DELETE.
|
||||||
|
These actions are performed against an account URI, in the following
|
||||||
|
general request structure::
|
||||||
|
|
||||||
|
METHOD /auth/<version>/<account> HTTP/1.1
|
||||||
|
|
||||||
|
The methods that can be used are detailed below.
|
||||||
|
|
||||||
|
Get Account Details
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
Account details can be retrieved by performing a GET request against
|
||||||
|
an account URI. On success, a JSON dictionary will be returned
|
||||||
|
containing the keys `account_id`, `services`, and `users`. The
|
||||||
|
`account_id` is the value used when creating service accounts. The
|
||||||
|
`services` value is a dict that represents valid storage cluster
|
||||||
|
endpoints, and which endpoint is the default. The 'users' value is a
|
||||||
|
list of dicts, each dict representing a user and currently only
|
||||||
|
containing the single key 'name'.
|
||||||
|
|
||||||
|
Valid Responses:
|
||||||
|
* 200: Success
|
||||||
|
* 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key
|
||||||
|
* 5xx: Internal error
|
||||||
|
|
||||||
|
Example Request::
|
||||||
|
|
||||||
|
GET /auth/<api version>/<account> HTTP/1.1
|
||||||
|
X-Auth-Admin-User: .super_user
|
||||||
|
X-Auth-Admin-Key: swauthkey
|
||||||
|
|
||||||
|
Example Curl Request::
|
||||||
|
|
||||||
|
curl -D - https://<endpoint>/auth/v2/<account> \
|
||||||
|
-H "X-Auth-Admin-User: .super_user" \
|
||||||
|
-H "X-Auth-Admin-Key: swauthkey"
|
||||||
|
|
||||||
|
Example Response::
|
||||||
|
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
|
||||||
|
{ "services":
|
||||||
|
{ "storage":
|
||||||
|
{ "default": "local",
|
||||||
|
"local": "https://<storage endpoint>/v1/<account_id>" },
|
||||||
|
},
|
||||||
|
"account_id": "<account_id>",
|
||||||
|
"users": [ { "name": "user1" },
|
||||||
|
{ "name": "user2" } ]
|
||||||
|
}
|
||||||
|
|
||||||
|
Create Account
|
||||||
|
--------------
|
||||||
|
|
||||||
|
An account can be created with a PUT request against a non-existent
|
||||||
|
account. By default, a newly created UUID4 will be used with the
|
||||||
|
reseller prefix as the account ID used when creating corresponding
|
||||||
|
service accounts. However, you can provide an X-Account-Suffix header
|
||||||
|
to replace the UUDI4 part.
|
||||||
|
|
||||||
|
Valid return codes:
|
||||||
|
* 200: Success
|
||||||
|
* 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key
|
||||||
|
* 5xx: Internal error
|
||||||
|
|
||||||
|
Example Request::
|
||||||
|
|
||||||
|
GET /auth/<api version>/<new_account> HTTP/1.1
|
||||||
|
X-Auth-Admin-User: .super_user
|
||||||
|
X-Auth-Admin-Key: swauthkey
|
||||||
|
|
||||||
|
Example Curl Request::
|
||||||
|
|
||||||
|
curl -D - https://<endpoint>/auth/v2/<new_account> \
|
||||||
|
-H "X-Auth-Admin-User: .super_user" \
|
||||||
|
-H "X-Auth-Admin-Key: swauthkey"
|
||||||
|
|
||||||
|
Example Response::
|
||||||
|
|
||||||
|
HTTP/1.1 201 Created
|
||||||
|
|
||||||
|
|
||||||
|
Delete Account
|
||||||
|
--------------
|
||||||
|
|
||||||
|
An account can be deleted with a DELETE request against an existing
|
||||||
|
account.
|
||||||
|
|
||||||
|
Valid Responses:
|
||||||
|
* 204: Success
|
||||||
|
* 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key
|
||||||
|
* 404: Account not found
|
||||||
|
* 5xx: Internal error
|
||||||
|
|
||||||
|
Example Request::
|
||||||
|
|
||||||
|
DELETE /auth/<api version>/<account> HTTP/1.1
|
||||||
|
X-Auth-Admin-User: .super_user
|
||||||
|
X-Auth-Admin-Key: swauthkey
|
||||||
|
|
||||||
|
Example Curl Request::
|
||||||
|
|
||||||
|
curl -XDELETE -D - https://<endpoint>/auth/v2/<account> \
|
||||||
|
-H "X-Auth-Admin-User: .super_user" \
|
||||||
|
-H "X-Auth-Admin-Key: swauthkey"
|
||||||
|
|
||||||
|
Example Response::
|
||||||
|
|
||||||
|
HTTP/1.1 204 No Content
|
||||||
|
|
||||||
|
|
||||||
|
User Services
|
||||||
|
=============
|
||||||
|
|
||||||
|
Each account in swauth contains zero or more users. These users can
|
||||||
|
be determined with the 'Get Account Details' API request against an
|
||||||
|
account.
|
||||||
|
|
||||||
|
Users in an account can be created, modified, and detailed as
|
||||||
|
described below by apply the appropriate REST verbs to a user URI, in
|
||||||
|
the following general request structure::
|
||||||
|
|
||||||
|
METHOD /auth/<version>/<account>/<user> HTTP/1.1
|
||||||
|
|
||||||
|
The methods that can be used are detailed below.
|
||||||
|
|
||||||
|
Get User Details
|
||||||
|
----------------
|
||||||
|
|
||||||
|
User details can be retrieved by performing a GET request against
|
||||||
|
a user URI. On success, a JSON dictionary will be returned as
|
||||||
|
described::
|
||||||
|
|
||||||
|
{"groups": [ # List of groups the user is a member of
|
||||||
|
{"name": "<act>:<usr>"},
|
||||||
|
# The first group is a unique user identifier
|
||||||
|
{"name": "<account>"},
|
||||||
|
# The second group is the auth account name
|
||||||
|
{"name": "<additional-group>"}
|
||||||
|
# There may be additional groups, .admin being a
|
||||||
|
# special group indicating an account admin and
|
||||||
|
# .reseller_admin indicating a reseller admin.
|
||||||
|
],
|
||||||
|
"auth": "plaintext:<key>"
|
||||||
|
# The auth-type and key for the user; currently only
|
||||||
|
# plaintext is implemented.
|
||||||
|
}
|
||||||
|
|
||||||
|
For example::
|
||||||
|
|
||||||
|
{"groups": [{"name": "test:tester"}, {"name": "test"},
|
||||||
|
{"name": ".admin"}],
|
||||||
|
"auth": "plaintext:testing"}
|
||||||
|
|
||||||
|
Valid Responses:
|
||||||
|
* 200: Success
|
||||||
|
* 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key
|
||||||
|
* 404: Unknown account
|
||||||
|
* 5xx: Internal error
|
||||||
|
|
||||||
|
Example Request::
|
||||||
|
|
||||||
|
GET /auth/<api version>/<account>/<user> HTTP/1.1
|
||||||
|
X-Auth-Admin-User: .super_user
|
||||||
|
X-Auth-Admin-Key: swauthkey
|
||||||
|
|
||||||
|
Example Curl Request::
|
||||||
|
|
||||||
|
curl -D - https://<endpoint>/auth/v2/<account>/<user> \
|
||||||
|
-H "X-Auth-Admin-User: .super_user" \
|
||||||
|
-H "X-Auth-Admin-Key: swauthkey"
|
||||||
|
|
||||||
|
Example Response::
|
||||||
|
|
||||||
|
HTTP/1.1 200 Ok
|
||||||
|
|
||||||
|
{ "groups": [ { "name": "<account>:<user>" },
|
||||||
|
{ "name": "<user>" },
|
||||||
|
{ "name": ".admin" } ],
|
||||||
|
"auth" : "plaintext:password" }
|
||||||
|
|
||||||
|
|
||||||
|
Create User
|
||||||
|
-----------
|
||||||
|
|
||||||
|
A user can be created with a PUT request against a non-existent
|
||||||
|
user URI. The new user's password must be set using the
|
||||||
|
``X-Auth-User-Key`` header. The user name MUST NOT start with a
|
||||||
|
period ('.'). This requirement is enforced by the API, and will
|
||||||
|
result in a 400 error.
|
||||||
|
|
||||||
|
Optional Headers:
|
||||||
|
|
||||||
|
* ``X-Auth-User-Admin: true``: create the user as an account admin
|
||||||
|
* ``X-Auth-User-Reseller-Admin: true``: create the user as a reseller
|
||||||
|
admin
|
||||||
|
|
||||||
|
Reseller admin accounts can only be created by the site admin, while
|
||||||
|
regular accounts (or account admin accounts) can be created by an
|
||||||
|
account admin, an appropriate reseller admin, or the site admin.
|
||||||
|
|
||||||
|
Note that PUT requests are idempotent, and the PUT request serves as
|
||||||
|
both a request and modify action.
|
||||||
|
|
||||||
|
Valid Responses:
|
||||||
|
* 200: Success
|
||||||
|
* 400: Invalid request (missing required headers)
|
||||||
|
* 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key, or insufficient priv
|
||||||
|
* 404: Unknown account
|
||||||
|
* 5xx: Internal error
|
||||||
|
|
||||||
|
Example Request::
|
||||||
|
|
||||||
|
PUT /auth/<api version>/<account>/<user> HTTP/1.1
|
||||||
|
X-Auth-Admin-User: .super_user
|
||||||
|
X-Auth-Admin-Key: swauthkey
|
||||||
|
X-Auth-User-Admin: true
|
||||||
|
X-Auth-User-Key: secret
|
||||||
|
|
||||||
|
Example Curl Request::
|
||||||
|
|
||||||
|
curl -XPUT -D - https://<endpoint>/auth/v2/<account>/<user> \
|
||||||
|
-H "X-Auth-Admin-User: .super_user" \
|
||||||
|
-H "X-Auth-Admin-Key: swauthkey" \
|
||||||
|
-H "X-Auth-User-Admin: true" \
|
||||||
|
-H "X-Auth-User-Key: secret"
|
||||||
|
|
||||||
|
Example Response::
|
||||||
|
|
||||||
|
HTTP/1.1 201 Created
|
||||||
|
|
||||||
|
Delete User
|
||||||
|
-----------
|
||||||
|
|
||||||
|
A user can be deleted by performing a DELETE request against a user
|
||||||
|
URI. This action can only be performed by an account admin,
|
||||||
|
appropriate reseller admin, or site admin.
|
||||||
|
|
||||||
|
Valid Responses:
|
||||||
|
* 200: Success
|
||||||
|
* 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key, or insufficient priv
|
||||||
|
* 404: Unknown account or user
|
||||||
|
* 5xx: Internal error
|
||||||
|
|
||||||
|
Example Request::
|
||||||
|
|
||||||
|
DELETE /auth/<api version>/<account>/<user> HTTP/1.1
|
||||||
|
X-Auth-Admin-User: .super_user
|
||||||
|
X-Auth-Admin-Key: swauthkey
|
||||||
|
|
||||||
|
Example Curl Request::
|
||||||
|
|
||||||
|
curl -XDELETE -D - https://<endpoint>/auth/v2/<account>/<user> \
|
||||||
|
-H "X-Auth-Admin-User: .super_user" \
|
||||||
|
-H "X-Auth-Admin-Key: swauthkey"
|
||||||
|
|
||||||
|
Example Response::
|
||||||
|
|
||||||
|
HTTP/1.1 204 No Content
|
||||||
|
|
||||||
|
|
||||||
|
Other Services
|
||||||
|
==============
|
||||||
|
|
||||||
|
There are several other swauth functions that can be performed, mostly
|
||||||
|
done via "pseudo-user" accounts. These are well-known user names that
|
||||||
|
are unable to be actually provisioned. These pseudo-users are
|
||||||
|
described below.
|
||||||
|
|
||||||
|
Set Service Endpoints
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
Service endpoint information can be retrived using the _`Get Account
|
||||||
|
Details` API method.
|
||||||
|
|
||||||
|
This function allows setting values within this section for
|
||||||
|
the <account>, allowing the addition of new service end points
|
||||||
|
or updating existing ones by performing a POST to the URI
|
||||||
|
corresponding to the pseudo-user ".services".
|
||||||
|
|
||||||
|
The body of the POST request should contain a JSON dict with
|
||||||
|
the following format::
|
||||||
|
|
||||||
|
{"service_name": {"end_point_name": "end_point_value"}}
|
||||||
|
|
||||||
|
There can be multiple services and multiple end points in the
|
||||||
|
same call.
|
||||||
|
|
||||||
|
Any new services or end points will be added to the existing
|
||||||
|
set of services and end points. Any existing services with the
|
||||||
|
same service name will be merged with the new end points. Any
|
||||||
|
existing end points with the same end point name will have
|
||||||
|
their values updated.
|
||||||
|
|
||||||
|
The updated services dictionary will be returned on success.
|
||||||
|
|
||||||
|
Valid Responses:
|
||||||
|
|
||||||
|
* 200: Success
|
||||||
|
* 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key
|
||||||
|
* 404: Account not found
|
||||||
|
* 5xx: Internal error
|
||||||
|
|
||||||
|
Example Request::
|
||||||
|
|
||||||
|
POST /auth/<api version>/<account>/.services HTTP/1.0
|
||||||
|
X-Auth-Admin-User: .super_user
|
||||||
|
X-Auth-Admin-Key: swauthkey
|
||||||
|
|
||||||
|
{"storage": { "local": "<new endpoint>" }}
|
||||||
|
|
||||||
|
Example Curl Request::
|
||||||
|
|
||||||
|
curl -XPOST -D - https://<endpoint>/auth/v2/<account>/.services \
|
||||||
|
-H "X-Auth-Admin-User: .super_user" \
|
||||||
|
-H "X-Auth-Admin-Key: swauthkey" --data-binary \
|
||||||
|
'{ "storage": { "local": "<new endpoint>" }}'
|
||||||
|
|
||||||
|
Example Response::
|
||||||
|
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
|
||||||
|
{"storage": {"default": "local", "local": "<new endpoint>" }}
|
||||||
|
|
||||||
|
Get Account Groups
|
||||||
|
------------------
|
||||||
|
|
||||||
|
Individual user group information can be retrived using the _`Get User
|
||||||
|
Details` API method.
|
||||||
|
|
||||||
|
This function allows retrieving all group information for all users in
|
||||||
|
an existing account. This can be achieved using a GET action against
|
||||||
|
a user URI with the pseudo-user ".groups".
|
||||||
|
|
||||||
|
The JSON dictionary returned will be a "groups" dictionary similar to
|
||||||
|
that documented in the _`Get User Details` method, but representing
|
||||||
|
the summary of all groups utilized by all active users in the account.
|
||||||
|
|
||||||
|
Valid Responses:
|
||||||
|
* 200: Success
|
||||||
|
* 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key
|
||||||
|
* 404: Account not found
|
||||||
|
* 5xx: Internal error
|
||||||
|
|
||||||
|
Example Request::
|
||||||
|
|
||||||
|
GET /auth/<api version>/<account>/.groups
|
||||||
|
X-Auth-Admin-User: .super_user
|
||||||
|
X-Auth-Admin-Key: swauthkey
|
||||||
|
|
||||||
|
Example Curl Request::
|
||||||
|
|
||||||
|
curl -D - https://<endpoint>/auth/v2/<account>/.groups \
|
||||||
|
-H "X-Auth-Admin-User: .super_user" \
|
||||||
|
-H "X-Auth-Admin-Key: swauthkey"
|
||||||
|
|
||||||
|
Example Response::
|
||||||
|
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
|
||||||
|
{ "groups": [ { "name": ".admin" },
|
||||||
|
{ "name": "<account>" },
|
||||||
|
{ "name": "<account>:user1" },
|
||||||
|
{ "name": "<account>:user2" } ] }
|
||||||
|
|
||||||
@ -65,6 +65,7 @@ Contents
|
|||||||
details
|
details
|
||||||
swauth
|
swauth
|
||||||
middleware
|
middleware
|
||||||
|
api
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
------------------
|
------------------
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user