Astakos API =========== This is Astakos API guide. Overview -------- Astakos service co-ordinates the access to resources (and the subsequent permission model) and acts as the single point of registry and entry to the GRNET cloud services. This document's goals is to describe the APIs to the outer world. Make sure you have read the :ref:`astakos` general architecture first. Document Revisions ^^^^^^^^^^^^^^^^^^ ========================= ================================ Revision Description ========================= ================================ 0.15 (December 02, 2013) Extent token api with validate token call 0.15 (October 29, 2013) Remove GET /authenticate in favor of POST /tokens 0.14 (June 03, 2013) Remove endpoint listing 0.14 (May 28, 2013) Extend token api with authenticate call 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. 0.6 (June 06, 2012) Split service and user API. 0.1 (Feb 10, 2012) Initial release. ========================= ================================ Get Services ^^^^^^^^^^^^ Returns a json formatted list containing information about the supported cloud services. ============================= ========= ================== Uri Method Description ============================= ========= ================== ``/ui/get_services`` GET Get cloud services ============================= ========= ================== Example reply: :: [{"url": "/", "icon": "home-icon.png", "name": "grnet cloud", "id": "1"}, {"url": "/okeanos.html", "name": "~okeanos", "id": "2"}, {"url": "/ui/", "name": "pithos", "id": "3"}] Get Menu ^^^^^^^^ Returns a json formatted list containing the cloud bar links. ========================= ========= ================== Uri Method Description ========================= ========= ================== ``/ui/get_menu`` GET Get cloud bar menu ========================= ========= ================== Example reply if request user is not authenticated: :: [{"url": "/ui/", "name": "Sign in"}] Example reply if request user is authenticated: :: [{"url": "/ui/", "name": "user@example.com"}, {"url": "/ui/landing", "name": "Dashboard"}, {"url": "/ui/logout", "name": "Sign out"}] User API Operations -------------------- The operations described in this chapter allow users to send feedback and get user uuid/displayname mappings. All the operations require a valid user token. Send feedback ^^^^^^^^^^^^^ Post user feedback. ========================== ========= ================== Uri Method Description ========================== ========= ================== ``/account/v1.0/feedback`` POST Send feedback ========================== ========= ================== | ==================== ============================ Request Header Name Value ==================== ============================ X-Auth-Token User authentication token ==================== ============================ | ====================== ========================= Request Parameter Name Value ====================== ========================= feedback_msg Feedback message feedback_data Additional information about service client status ====================== ========================= | =========================== ===================== Return Code Description =========================== ===================== 200 (OK) The request succeeded 502 (Bad Gateway) Send feedback failure 400 (Bad Request) Method not allowed or invalid message data 401 (Unauthorized) Missing or expired user token 500 (Internal Server Error) The request cannot be completed because of an internal error =========================== ===================== .. warning:: The service is also available under ``/feedback``. It will be removed in the next version. Get User catalogs ^^^^^^^^^^^^^^^^^ Return a json formatted dictionary containing information about a specific user =============================== ========= ================== Uri Method Description =============================== ========= ================== ``/account/v1.0/user_catalogs`` POST Get 2 catalogs containing uuid to displayname mapping and the opposite =============================== ========= ================== | ==================== ============================ Request Header Name Value ==================== ============================ X-Auth-Token User authentication token ==================== ============================ | The request body is a json formatted dictionary containing a list with uuids and another list of displaynames to translate. Example request content: :: {"displaynames": ["user1@example.com", "user2@example.com"], "uuids":["ff53baa9-c025-4d56-a6e3-963db0438830", "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8"]} Example reply: :: {"displayname_catalog": {"user1@example.com": "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8", "user2@example.com": "816351c7-7405-4f26-a968-6380cf47ba1f"}, 'uuid_catalog': {"a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8": "user1@example.com", "ff53baa9-c025-4d56-a6e3-963db0438830": "user2@example.com"}} | =========================== ===================== Return Code Description =========================== ===================== 200 (OK) The request succeeded 400 (Bad Request) Method not allowed or request body is not json formatted 401 (Unauthorized) Missing or expired or invalid user token 500 (Internal Server Error) The request cannot be completed because of an internal error =========================== ===================== .. warning:: The service is also available under ``/user_catalogs``. It will be removed in the next version. Service API Operations ---------------------- The operations described in this chapter allow services to get user uuid/displayname mappings. All the operations require a valid service token. Get User catalogs ^^^^^^^^^^^^^^^^^ Return a json formatted dictionary containing information about a specific user ======================================= ========= ================== Uri Method Description ======================================= ========= ================== ``/account/v1.0/service/user_catalogs`` POST Get 2 catalogs containing uuid to displayname mapping and the opposite ======================================= ========= ================== | ==================== ============================ Request Header Name Value ==================== ============================ X-Auth-Token Service authentication token ==================== ============================ | The request body is a json formatted dictionary containing a list with uuids and another list of displaynames to translate. If instead of list null is passed then the response contains the information for all the system users (For discretion purposes this behavior is **not** exposed in the respective call of the User API). Example request content: :: {"displaynames": ["user1@example.com", "user2@example.com"], "uuids":["ff53baa9-c025-4d56-a6e3-963db0438830", "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8"]} Example reply: :: {"displayname_catalog": {"user1@example.com": "a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8", "user2@example.com": "816351c7-7405-4f26-a968-6380cf47ba1f"}, 'uuid_catalog': {"a9dc21d2-bcb2-4104-9a9e-402b7c70d6d8": "user1@example.com", "ff53baa9-c025-4d56-a6e3-963db0438830": "user2@example.com"}} | =========================== ===================== Return Code Description =========================== ===================== 200 (OK) The request succeeded 400 (Bad Request) Method not allowed or request body is not json formatted 401 (Unauthorized) Missing or expired or invalid service token 500 (Internal Server Error) The request cannot be completed because of an internal error =========================== ===================== .. warning:: The service is also available under ``/service/api/user_catalogs``. It will be removed in the next version. Tokens API Operations ---------------------- Authenticate ^^^^^^^^^^^^ This call takes the user token or the user uuid/token pair, authenticates the user and returns information about the token, its holder as well as a list of services the user can access. If no request body is provided (the request content length is missing or equals to 0), the call operates in public mode, attempts no authentication and returns only the service catalog. ========================================= ========= ================== Uri Method Description ========================================= ========= ================== ``/identity/v2.0/tokens`` POST Checks whether the provided token is valid and conforms with the provided uuid (if present) and returns back information about the user ========================================= ========= ================== The input should be json formatted. Example request: :: { "auth":{ "token":{ "id":"CDEe2k0T/HdiJWBMMbHyOA" }, "tenantName":"c18088be-16b1-4263-8180-043c54e22903" } } or :: { "auth":{ "passwordCredentials":{ "username":"c18088be-16b1-4263-8180-043c54e22903", "password":"CDEe2k0T/HdiJWBMMbHyOA" }, "tenantName":"c18088be-16b1-4263-8180-043c54e22903" } } The tenantName in the above requests is optional. The response is json formatted unless it is requested otherwise via format request parameter or Accept header. Example json response: :: {"access": { "token": { "expires": "2013-06-19T15:23:59.975572+00:00", "id": "CDEe2k0T/HdiJWBMMbHyOA==", "tenant": { "id": "c18088be-16b1-4263-8180-043c54e22903", "name": "Firstname Lastname" } }, "serviceCatalog": [ {"endpoints_links": [], "endpoints": [{ "SNF:uiURL": "https://accounts.example.synnefo.org/ui", "versionId": "v1.0", "publicURL": "https://accounts.example.synnefo.org/account/v1.0"}], "type": "account", "name": "astakos_account"}, {"endpoints_links": [], "endpoints": [{ "SNF:uiURL": "https://accounts.example.synnefo.org/ui", "versionId": "v2.0", "publicURL": "https://accounts.example.synnefo.org/account/v2.0"}], "type": "identity", "name": "astakos_identity"}, {"endpoints_links": [], "endpoints": [{ "SNF:uiURL": "https://cyclades.example.synnefo.org/ui", "versionId": "v2.0", "publicURL": "https://cyclades.example.synnefo.org/cyclades/compute/v2.0"}], "type": "compute", "name": "cyclades_compute"}, {"endpoints_links": [], "endpoints": [{ "SNF:uiURL": "https://cyclades.example.synnefo.org/ui", "versionId": "v1.0", "publicURL": "https://cyclades.example.synnefo.org/cyclades/vmapi/v1.0"}], "type": "cyclades_vmapi", "name": "cyclades_vmapi"}, {"endpoints_links": [], "endpoints": [{ "SNF:uiURL": "https://cyclades.example.synnefo.org/ui", "versionId": "v1.0", "publicURL": "https://cyclades.example.synnefo.org/cyclades/image/v1.0"}], "type": "image", "name": "cyclades_plankton"}, {"endpoints_links": [], "endpoints": [{ "SNF:uiURL": "https://object-store.example.synnefo.org/ui", "versionId": "v2.0", "publicURL": "https://object-store.example.synnefo.org/pithos/public/v2.0"}], "type": "public", "name": "pithos_public"}, {"endpoints_links": [], "endpoints": [{ "SNF:uiURL": "https://object-store.example.synnefo.org/ui", "versionId": "v1", "publicURL": "https://object-store.example.synnefo.org/pithos/object-store/v1"}], "type": "object-store", "name": "pithos_object-store"}, {"endpoints_links": [], "endpoints": [{ "SNF:uiURL": "https://accounts.example.synnefo.org/ui", "versionId": "", "SNF:webloginURL": "http://localhost:8080/astakos/weblogin" "publicURL": "https://accounts.example.synnefo.org/astakos/weblogin"}], "type": "astakos_weblogin", "name": "astakos_weblogin"}], "user": { "roles_links": [], "id": "c18088be-16b1-4263-8180-043c54e22903", "roles": [{"id": 1, "name": "default"}], "name": "Firstname Lastname"}}} Example xml response: :: | =========================== ===================== Return Code Description =========================== ===================== 200 (OK) The request succeeded 400 (Bad Request) Method not allowed or invalid request format or missing expected input or not consistent tenantName 401 (Unauthorized) Invalid token or invalid creadentials or tenantName does not comply with the provided token 500 (Internal Server Error) The request cannot be completed because of an internal error =========================== ===================== Validate token ^^^^^^^^^^^^^^ This calls validates an access token and confirms that it belongs to a specified scope. ========================================= ========= ================== Uri Method Description ========================================= ========= ================== ``/identity/v2.0/tokens/`` GET Validates an access token and confirms that it belongs to a specified scope. ========================================= ========= ================== | ====================== ========================= Request Parameter Name Value ====================== ========================= belongsTo Validates that a access token has the specified scope. The belongsTo parameter is optional. ====================== ========================= Example response :: {"access": { "token": { "expires": "2013-12-02T15:57:34.300266+00:00", "id": "2YotnFZFEjr1zCsicMWpAA", "tenant": { "id": "c18088be-16b1-4263-8180-043c54e22903", "name": "Firstname Lastname" } }, "user": { "roles_links": [], "id": "c18088be-16b1-4263-8180-043c54e22903", "roles": [{"id": 1, "name": "default"}], "name": "Firstname Lastname"}}} | =========================== ===================== Return Code Description =========================== ===================== 404 Unknown or expired access token or the access token does not belong to the specified scope =========================== =====================