From debeb3fd3033ddd58b3c54887ab87b6a089535f7 Mon Sep 17 00:00:00 2001 From: rpedde Date: Mon, 6 Jun 2011 14:01:16 -0500 Subject: [PATCH] Add first pass of API docs for swift internal API. --- doc/source/api.rst | 463 +++++++++++++++++++++++++++++++++++++++++++ doc/source/index.rst | 1 + 2 files changed, 464 insertions(+) create mode 100644 doc/source/api.rst diff --git a/doc/source/api.rst b/doc/source/api.rst new file mode 100644 index 0000000..4c7801b --- /dev/null +++ b/doc/source/api.rst @@ -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// HTTP/1.1 + X-Auth-Admin-User: .super_user + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -D - https:///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// 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// HTTP/1.1 + X-Auth-Admin-User: .super_user + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -D - https:///auth/v2/ \ + -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:///v1/" }, + }, + "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// HTTP/1.1 + X-Auth-Admin-User: .super_user + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -D - https:///auth/v2/ \ + -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// HTTP/1.1 + X-Auth-Admin-User: .super_user + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -XDELETE -D - https:///auth/v2/ \ + -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/// 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": ":"}, + # The first group is a unique user identifier + {"name": ""}, + # The second group is the auth account name + {"name": ""} + # There may be additional groups, .admin being a + # special group indicating an account admin and + # .reseller_admin indicating a reseller admin. + ], + "auth": "plaintext:" + # 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/// HTTP/1.1 + X-Auth-Admin-User: .super_user + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -D - https:///auth/v2// \ + -H "X-Auth-Admin-User: .super_user" \ + -H "X-Auth-Admin-Key: swauthkey" + +Example Response:: + + HTTP/1.1 200 Ok + + { "groups": [ { "name": ":" }, + { "name": "" }, + { "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/// 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:///auth/v2// \ + -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/// HTTP/1.1 + X-Auth-Admin-User: .super_user + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -XDELETE -D - https:///auth/v2// \ + -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 , 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///.services HTTP/1.0 + X-Auth-Admin-User: .super_user + X-Auth-Admin-Key: swauthkey + + {"storage": { "local": "" }} + +Example Curl Request:: + + curl -XPOST -D - https:///auth/v2//.services \ + -H "X-Auth-Admin-User: .super_user" \ + -H "X-Auth-Admin-Key: swauthkey" --data-binary \ + '{ "storage": { "local": "" }}' + +Example Response:: + + HTTP/1.1 200 OK + + {"storage": {"default": "local", "local": "" }} + +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///.groups + X-Auth-Admin-User: .super_user + X-Auth-Admin-Key: swauthkey + +Example Curl Request:: + + curl -D - https:///auth/v2//.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": "" }, + { "name": ":user1" }, + { "name": ":user2" } ] } + diff --git a/doc/source/index.rst b/doc/source/index.rst index 8b96852..099055c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -65,6 +65,7 @@ Contents details swauth middleware + api Indices and tables ------------------