code.grnet.gr Git - kamaki/blob - docs/developers/clients-api.rst

   1 Creating applications with kamaki API
   2 =====================================
   3
   4
   5 Kamaki features a clients API for building third-party client applications that communicate with OpenStack and / or Synnefo cloud services. The package is called kamaki.clients and contains a number of
   6
   7 A good example of an application build on kamaki.clients is kamaki.cli, the command line interface of kamaki.
   8
   9 Since synnefo services are build as OpenStack extensions, an inheritance approach has been chosen for implementing clients for both. In specific, the *compute*, *storage* and *image* modules are clients of the OS compute, OS storage, respectively. On the contrary, all the other modules are Synnefo extensions (*cyclades* extents *compute*, *pithos* and *pithos_rest_api* extent *storage*) or novel synnefo services (e.g. *astakos* for IM, *image* for *plankton*).
  10
  11 Setup a client instance
  12 -----------------------
  13
  14 External applications may instantiate one or more kamaki clients.
  15
  16 .. code-block:: python
  17     :emphasize-lines: 1
  18
  19     Example 1.1: Instantiate Cyclades and Pithos client
  20
  21
  22     from kamaki.clients.cyclades import CycladesClient
  23     from kamaki.clients.pithos import PithosClient
  24
  25     my_cyclades_client = CycladesClient(base_url, token)
  26     my_pithos_client = PithosClient(base_url, token, account, container)
  27
  28 .. note:: *cyclades* and *pithos* clients inherit all methods of *compute* and *storage* clients respectively. Separate compute or storage objects should be used only when implementing applications for strict OS Compute or OS Storage services.
  29
  30 .. note:: *account* variable is usually acquired by the following user call
  31
  32     .. code-block:: python
  33
  34         from kamaki.clients.astakos import AstakosClient
  35         astakos = AstakosClient(astakos_base_url, token)
  36         account = astakos.term('uuid')
  37
  38 Use client methods
  39 ------------------
  40
  41 Client methods can now be called. Developers are advised to consult :ref:`the-client-api-ref` for details on the available methods and how to use them.
  42
  43 In the following example, the *cyclades* and *pithos* clients of example 1.1 are used to extract some information, that is then printed to the standard output.
  44
  45
  46 .. code-block:: python
  47     :emphasize-lines: 1,2
  48
  49     Example 1.2: Print server name and OS for server with server_id
  50                 Print objects in container mycont
  51
  52
  53     srv = my_cyclades_client.get_server_info(server_id)
  54     print("Server Name: %s (with OS %s" % (srv['name'], srv['os']))
  55
  56     obj_list = my_pithos_client.list_objects(mycont)
  57     for obj in obj_list:
  58         print('  %s of %s bytes' % (obj['name'], obj['bytes']))
  59
  60 .. code-block:: console
  61     :emphasize-lines: 1
  62
  63     Run of examples 1.1 + 1.2
  64
  65
  66     $ python test_script.py
  67     Server Name: A Debian Server (with OS Debian Base)
  68       lala.txt of 34 bytes
  69       test.txt of 1232 bytes
  70       testDir/ of 0 bytes
  71     $
  72
  73 Error handling
  74 --------------
  75
  76 The kamaki.clients standard error is ClientError. A ClientError is raised for any kind of kamaki.clients errors (errors reported by servers, type errors in arguments, etc.).
  77
  78 A ClientError contains::
  79
  80     message     The error message.
  81     status      An optional error code, e.g. after a server error.
  82     details     Optional list of messages with error details.
  83
  84 The following example concatenates examples 1.1 and 1.2 plus error handling
  85
  86 .. code-block:: python
  87
  88     Example 1.3: Error handling
  89
  90
  91     from kamaki.clients.cyclades import CycladesClient
  92     from kamaki.clients.pithos import PithosClient
  93
  94     try:
  95         my_cyclades_client = CycladesClient(base_url, token)
  96     except ClientError:
  97         print('Failed to initialize Cyclades client')
  98
  99     try:
 100         my_pithos_client = PithosClient(base_url, token, account, container)
 101     except ClientError:
 102         print('Failed to initialize Pithos+ client')
 103
 104     try:
 105         srv = my_cyclades_client.get_server_info(server_id)
 106         print("Server Name: %s (with OS %s" % (srv['name'], srv['os']))
 107
 108         obj_list = my_pithos_client.list_objects(mycont)
 109         for obj in obj_list:
 110             print('  %s of %s bytes' % (obj['name'], obj['bytes']))
 111     except ClientError as e:
 112         print('Error: %s' % e)
 113         if e.status:
 114             print('- error code: %s' % e.status)
 115         if e.details:
 116             for detail in e.details:
 117                 print('- %s' % detail)