Update docs and Changelog for get_endpoint_url

Closes #2

Changelog

@@ -23,4 +23,5 @@ Features:
 - Datetime support in DateArgument
 - Resources can be reassigned to projects
 - Update account API commands to reflect changes in synnefo 0.16
+- Implement a get_endpoint_url method and use it
 

docs/developers/clients-api.rst

@@ -2,8 +2,8 @@ Creating applications with kamaki API
 =====================================
 
 Kamaki features a clients API for building third-party client applications that
-communicate with Synnefo and (in most cases) OpenStack cloud services. The package is
-called *kamaki.clients* and serves as a library.
+communicate with Synnefo and (in most cases) OpenStack cloud services. The
+package is called *kamaki.clients* and serves as a library.
 
 A showcase of an application built on *kamaki.clients* is *kamaki.cli*, the
 command line interface of kamaki.
@@ -46,32 +46,28 @@ respectively.
 Using endpoints to get the authentication url
 ---------------------------------------------
 
-In OpenStack, each service (e.g., `compute`, `object-store`, etc.) has a number
-of `endpoints`. These `endpoints` are URIs which are used by kamaki as prefixes
-to form the corresponding API calls. Client applications need just one of these
-`endpoints`, namely the `publicURL` (also referred to as `publicURL` in the
-internals of kamaki client libraries).
+Each client is initialized with a URL called ``the endpoint URL``. To get one,
+an AstakosClient should be initialized first. The AstakosClient is an Astakos
+client class. Astakos implements the OpenStack Identity API and the Synnefo
+Account API. The astakos library features a simple call (``get_endpoint_url``)
+which returns the initialization URL for a given service type (e.g., 'compute',
+'object-store', 'network', 'image')
 
-Here are instructions for getting the publicURL for a service::
+Kamaki features a library of clients. Each client abides to a service type,
+stored in ``service_type`` attribute in the client class.
 
-    1. From the deployment UI get the AUTHENTICATION_URL and TOKEN
-        (Example 1.2)
-    2. Use them to instantiate an AstakosClient
-        (Example 1.2)
-    3. Use AstakosClient instance to get endpoints for the service of interest
-        (Example 1.3)
-    4. The 'publicURL' endpoint is the URL we are looking for
-        (Example 1.3)
+The values of ``service_type`` for each client are shown bellow::
 
-The AstakosClient is a client for the Synnefo/Astakos server. Synnefo/Astakos
-is an identity server that implements the OpenStack identity API and it
-can be used to get the URLs needed for API calls URL construction. The astakos
-kamaki client library simplifies this process.
+    storage.StorageClient, pithos.PithosClient            --> object-store
+    compute.ComputeClient, cyclades.CycladesClient        --> compute
+    network.NetworkClient, cyclades.CycladesNetworkClient --> network
+    image.ImageClient                                     --> image
+    astakos.AstakosClient                                 --> identity
 
 Let's review with a few examples.
 
 First, an astakos client must be initialized (Example 1.2). An
-AUTHENTICATION_URL and a TOKEN can be acquired from the Synnefo deployment UI.
+AUTHENTICATION_URL and a TOKEN can be acquired from the service web UI.
 
 .. code-block:: python
     :emphasize-lines: 1
@@ -82,32 +78,19 @@ AUTHENTICATION_URL and a TOKEN can be acquired from the Synnefo deployment UI.
     astakos = AstakosClient(AUTHENTICATION_URL, TOKEN)
         
 
-Next, the astakos client can be used to retrieve the `publicURL` values for the
-services of interest. In this case (Example 1.3) they are *cyclades* (compute)
-and *pithos* (object-store). A number of endpoints is related to each service,
-but kamaki clients only need the ones labeled ``publicURL``.
+Next, the astakos client can be used to retrieve the URL for each service. In
+this case (Example 1.3) we need a *compute* and an *object-store* URL. They
+will be used to initialize a *cyclades* and a *pithos* client respectively.
 
 .. code-block:: python
     :emphasize-lines: 1
 
-    Example 1.3: Retrieve cyclades and pithos publicURL values
-
-    cyclades_endpoints = astakos.get_service_endpoints('compute')
-    cyclades_URL = cyclades_endpoints['publicURL']
-
-    pithos_endpoints = astakos.get_service_endpoints('object-store')
-    pithos_URL = pithos_endpoints['publicURL']
+    Example 1.3: Retrieve cyclades and pithos URLs
 
-The ``get_service_endpoints`` method is called with the service name as an
-argument. Here are the service names for the kamaki clients::
-
-    storage.StorageClient, pithos.PithosClient            --> object-store
-    compute.ComputeClient, cyclades.CycladesClient        --> compute
-    network.NetworkClient, cyclades.CycladesNetworkClient --> network
-    image.ImageClient                                     --> image
-    astakos.AstakosClient                                 --> identity, account
+    cyclades_URL = astakos.get_endpoint_url(CycladesClient.service_type)
+    pithos_URL = astakos.get_endpoint_url(PithosClent.service_type)
 
-For example
+It's time to initialize both clients.
 
 .. code-block:: python
     :emphasize-lines: 1
@@ -199,8 +182,7 @@ The following example concatenates examples 1.1 to 1.4 plus error handling
         raise
 
     try:
-        cyclades_endpoints = astakos.get_service_endpoints('compute')
-        CYCLADES_URL = cyclades_endpoints['publicURL']
+        CYCLADES_URL = astakos.get_endpoint_url(CycladesClient.service_type)
     except ClientError:
         print('Failed to get endpoints for cyclades')
 
@@ -210,8 +192,7 @@ The following example concatenates examples 1.1 to 1.4 plus error handling
         print('Failed to initialize Cyclades client')
 
     try:
-        pithos_endpoints = astakos.get_service_endpoints('object-store')
-        PITHOS_URL = pithos_endpoints['publicURL']
+        PITHOS_URL = astakos.get_endpoint_url(PithosClient.service_type)
     except ClientError:
         print('Failed to get endpoints for pithos')
 
@@ -257,7 +238,7 @@ Batch-create servers
 
     astakos = AstakosClient(AUTHENTICATION_URL, TOKEN)
 
-    CYCLADES_URL = astakos.get_service_endpoints('compute')['publicURL']
+    CYCLADES_URL = astakos.get_endpoint_url(CycladesClient.service_type)
     cyclades = CycladesClient(CYCLADES_URL, TOKEN)
 
     #  (name, flavor-id, image-id)
@@ -300,11 +281,11 @@ Register a banch of pre-uploaded images
     astakos = AstakosClient(AUTHENTICATION_URL, TOKEN)
     USER_UUID = astakos.user_info['id']
 
-    PITHOS_URL = astakos.get_service_endpoints('object-store')['publicURL']
+    PITHOS_URL = astakos.get_endpoint_url(PithosClient.service_type)
     pithos = PithosClient(
         PITHOS_URL, TOKEN, account=USER_UUID, container=IMAGE_CONTAINER)
 
-    IMAGE_URL = astakos.get_service_endpoints('image')['publicURL']
+    IMAGE_URL = astakos.get_endpoint_url(ImageClient.service_type)
     plankton = ImageClient(IMAGE_URL, TOKEN)
 
     for img in pithos.list_objects():
@@ -336,12 +317,12 @@ Two servers and a private network
 
     astakos = AstakosClient(AUTHENTICATION_URL, TOKEN)
 
-    NETWORK_URL = astakos.get_service_endpoints('network')['publicURL']
+    NETWORK_URL = astakos.get_endpoint_url(CycladesNetworkClient.service_type)
     network = CycladesNetworkClient(NETWORK_URL, TOKEN)
 
     net = network.create_network(type='MAC_FILTERED', name='My private network')
 
-    CYCLADES_URL = astakos.get_service_endpoints('compute')['publicURL']
+    CYCLADES_URL = astakos.get_endpoint_url(CycladesClient.service_type)
     cyclades = CycladesClient(CYCLADES_URL, TOKEN)
 
     FLAVOR_ID = 'put your flavor id here'

docs/developers/showcase.rst

@@ -82,18 +82,14 @@ This is the plan:
             AUTH_URL, AUTH_TOKEN))
         raise
 
-    #  3. Get the endpoints
-    #  Identity, Account --> astakos
-    #  Compute, Network --> cyclades
-    #  Object-store --> pithos
-    #  Image --> plankton
+    #  3. Get the endpoint URLs
     try:
         endpoints = dict(
             astakos=AUTH_URL,
-            cyclades=auth.get_service_endpoints('compute')['publicURL'],
-            network=auth.get_service_endpoints('network')['publicURL'],
-            pithos=auth.get_service_endpoints('object-store')['publicURL'],
-            plankton=auth.get_service_endpoints('image')['publicURL']
+            cyclades=auth.get_endpoint_url(CycladesClient.service_type),
+            network=auth.get_endpoint_url(CycladesNetworkClient.service_type),
+            pithos=auth.get_endpoint_url(PithosClient.service_type),
+            plankton=auth.get_endpoint_url(ImageClient.service_type)
             )
         user_id = auth.user_info['id']
     except ClientError:
@@ -641,11 +637,13 @@ logging more. We also added some command line interaction candy.
         print(' Get the endpoints')
         try:
             endpoints = dict(
-                astakos=auth.get_service_endpoints('identity')['publicURL'],
-                cyclades=auth.get_service_endpoints('compute')['publicURL'],
-                network=auth.get_service_endpoints('network')['publicURL'],
-                pithos=auth.get_service_endpoints('object-store')['publicURL'],
-                plankton=auth.get_service_endpoints('image')['publicURL']
+                #  Astakos implements identity and account APIs - The endpoint
+                #  URL is the same for both services
+                astakos=auth.get_endpoint_url('identity'),
+                cyclades=auth.get_endpoint_url(CycladesClient.service_type),
+                network=auth.get_endpoint_url(CycladesNetworkClient.service_type),
+                pithos=auth.get_endpoint_url(PithosClient.service_type),
+                plankton=auth.get_endpoint_url(ImageClient.service_type)
                 )
             user_id = auth.user_info['id']
         except ClientError: