astakos: update api docs

docs/astakos-api-guide.rst

@@ -20,6 +20,7 @@ Document Revisions
 =========================  ================================
 Revision                   Description
 =========================  ================================
+0.14 (May 23, 2013)        Extend api to list endpoints
 0.14 (May 14, 2013)        Do not serve user quotas in :ref:`authenticate-api-label`
 0.14 (May 02, 2013)        Change URIs (keep also the old ones until the next version)
 0.13 (January 21, 2013)    Extend api to export user presentation & quota information.
@@ -251,11 +252,11 @@ Get User catalogs
 
 Return a json formatted dictionary containing information about a specific user
 
-===================================== =========  ==================
-Uri                                   Method     Description
-===================================== =========  ==================
+====================================== =========  ==================
+Uri                                    Method     Description
+====================================== =========  ==================
 ``/astakos/api/service/user_catalogs`` POST       Get 2 catalogs containing uuid to displayname mapping and the opposite
-===================================== =========  ==================
+====================================== =========  ==================
 
 |
 
@@ -301,3 +302,88 @@ Return Code                 Description
 
 .. warning:: The service is also available under ``/service/api/user_catalogs``.
      It  will be removed in the next version.
+
+Tokens API Operations
+----------------------
+
+Get endpoints
+^^^^^^^^^^^^^
+
+Return a json (or xml) formatted dictionary containing information about registered endpoints
+
+========================================= =========  ==================
+Uri                                       Method     Description
+========================================= =========  ==================
+``/astakos/api/tokens/<token>/endpoints`` GET        Returns a list registered endpoints
+========================================= =========  ==================
+
+|
+
+====================  ============================
+Request Header Name   Value
+====================  ============================
+X-Auth-Token          User authentication token
+====================  ============================
+
+|
+
+======================  ============================
+Request Parameter Name  Value
+
+======================  ============================
+belongsTo               Check that the token belongs to a supplied user
+marker                  Return endpoints (ordered by ID) whose ID is higher than the marker
+limit                   Maximum number of endpoints to return
+======================  ============================
+
+|
+
+Example json reply:
+
+::
+
+    {'endpoint_links': [{'href': '/astakos/api/tokens/0000/endpoints?marker=7&limit=10000',
+       'rel': 'next'}],
+     'endpoints': [
+      {'adminURL': 'https://node1.example.com/ui/',
+       'id': 5,
+       'internalURL': 'https://node1.example.com/ui/',
+       'name': 'cyclades',
+       'publicURL': 'https://node1.example.com/ui/',
+       'region': 'cyclades',
+       'type': None},
+      {'adminURL': 'https://node2.example.com/v1',
+       'id': 6,
+       'internalURL': 'https://node2.example.com/ui/',
+       'name': 'pithos',
+       'publicURL': 'https://node2.example.com/ui/',
+       'region': 'pithos',
+       'type': None},
+     ]}
+
+
+Example xml reply:
+
+::
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <endpoints xmlns="http://docs.openstack.org/identity/api/v2.0">
+        <endpoint "name"="cyclades" "region"="cyclades" "internalURL"="https://node1.example.com/ui/" "adminURL"="https://node1.example.com/ui/" "id"="5" "publicURL"="https://node1.example.com/ui/" />
+        <endpoint "name"="pithos" "region"="pithos" "internalURL"="https://node2.example.com/ui/" "adminURL"="https://node2.example.com/v1" "id"="6" "publicURL"="https://node2.example.com/ui/" />
+    </endpoints>
+    <endpoint_links>
+            <endpoint_link "href"="/astakos/api/tokens/0000/endpoints?marker=7&amp;limit=10000" "rel"="next" />
+    </endpoint_links>
+
+
+|
+
+=========================== =====================
+Return Code                 Description
+=========================== =====================
+200 (OK)                    The request succeeded
+400 (Bad Request)           Method not allowed or token does not belong to the specific user
+401 (Unauthorized)          Missing or expired or invalid service token
+403 (Forbidden)             Path token does not comply with X-Auth-Token
+500 (Internal Server Error) The request cannot be completed because of an internal error
+=========================== =====================