root / docs / developers / clients-api.rst @ d88ba587
History | View | Annotate | Download (4 kB)
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*, *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 a Cyclades 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 |
Use client methods |
31 |
------------------ |
32 |
|
33 |
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. |
34 |
|
35 |
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. |
36 |
|
37 |
|
38 |
.. code-block:: python |
39 |
:emphasize-lines: 1,2 |
40 |
|
41 |
Example 1.2: Print server name and OS for server with server_id |
42 |
Print objects in container mycont |
43 |
|
44 |
|
45 |
srv = my_cyclades_client.get_server_info(server_id) |
46 |
print("Server Name: %s (with OS %s" % (srv['name'], srv['os'])) |
47 |
|
48 |
obj_list = my_pithos_client.list_objects(mycont) |
49 |
for obj in obj_list: |
50 |
print(' %s of %s bytes' % (obj['name'], obj['bytes'])) |
51 |
|
52 |
.. code-block:: console |
53 |
:emphasize-lines: 1 |
54 |
|
55 |
Run of examples 1.1 + 1.2 |
56 |
|
57 |
|
58 |
$ python test_script.py |
59 |
Server Name: A Debian Server (with OS Debian Base) |
60 |
lala.txt of 34 bytes |
61 |
test.txt of 1232 bytes |
62 |
testDir/ of 0 bytes |
63 |
$ |
64 |
|
65 |
Error handling |
66 |
-------------- |
67 |
|
68 |
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.). |
69 |
|
70 |
A ClientError contains:: |
71 |
|
72 |
message The error message. |
73 |
status An optional error code, e.g. after a server error. |
74 |
details Optional list of messages with error details. |
75 |
|
76 |
The following example concatenates examples 1.1 and 1.2 plus error handling |
77 |
|
78 |
.. code-block:: python |
79 |
|
80 |
Example 1.3: Error handling |
81 |
|
82 |
|
83 |
from kamaki.clients.cyclades import CycladesClient |
84 |
from kamaki.clients.pithos import PithosClient |
85 |
|
86 |
try: |
87 |
my_cyclades_client = CycladesClient(base_url, token) |
88 |
except ClientError: |
89 |
print('Failed to initialize Cyclades client') |
90 |
|
91 |
try: |
92 |
my_pithos_client = PithosClient(base_url, token, account, container) |
93 |
except ClientError: |
94 |
print('Failed to initialize Pithos+ client') |
95 |
|
96 |
try: |
97 |
srv = my_cyclades_client.get_server_info(server_id) |
98 |
print("Server Name: %s (with OS %s" % (srv['name'], srv['os'])) |
99 |
|
100 |
obj_list = my_pithos_client.list_objects(mycont) |
101 |
for obj in obj_list: |
102 |
print(' %s of %s bytes' % (obj['name'], obj['bytes'])) |
103 |
except ClientError as e: |
104 |
print('Error: %s' % e) |
105 |
if e.status: |
106 |
print('- error code: %s' % e.status) |
107 |
if e.details: |
108 |
for detail in e.details: |
109 |
print('- %s' % detail) |