From 35c9b6520222e05bff35d341bb7057faace99458 Mon Sep 17 00:00:00 2001
From: Markus Zoeller <mzoeller@de.ibm.com>
Date: Tue, 11 Nov 2014 09:48:57 +0100
Subject: [PATCH] Adds basic examples of v2 API usage

Closes-Bug: 1321438

Change-Id: I7c4a5db5bd498c6fb1dd2f4fdbf347b8d4c02c9a
---
 doc/source/apiv2.rst | 77 ++++++++++++++++++++++++++++++++++++++++++++
 doc/source/index.rst |  1 +
 2 files changed, 78 insertions(+)
 create mode 100644 doc/source/apiv2.rst

diff --git a/doc/source/apiv2.rst b/doc/source/apiv2.rst
new file mode 100644
index 00000000..ef6fb716
--- /dev/null
+++ b/doc/source/apiv2.rst
@@ -0,0 +1,77 @@
+Python API v2
+=============
+
+To create a client::
+
+   from keystoneclient.auth.identity import v2 as identity
+   from keystoneclient import session
+   from glanceclient import Client
+
+   auth = identity.Password(auth_url=AUTH_URL,
+                            username=USERNAME,
+                            password=PASSWORD,
+                            tenant_name=PROJECT_ID)
+
+   sess = session.Session(auth=auth)
+   token = auth.get_token(sess)
+
+   glance = Client('2', endpoint=OS_IMAGE_ENDPOINT, token=token)
+
+
+Create
+------
+Create a new image::
+
+   image = glance.images.create(name="myNewImage")
+   glance.images.upload(image.id, open('/tmp/myimage.iso', 'rb'))
+
+Show
+----
+Describe a specific image::
+
+   glance.images.get(image.id)
+
+Update
+------
+Update a specific image::
+
+   # update with a list of image attribute names and their new values
+   glance.images.update(image.id, name="myNewImageName")
+
+Delete
+------
+Delete specified image(s)::
+
+   glance.images.delete(image.id)
+
+List
+----
+List images you can access::
+
+   for image in glance.images.list():
+      print image
+
+Download
+--------
+Download a specific image::
+
+   d = glance.images.data(image.id)
+
+Share an Image
+--------------
+Share a specific image with a tenant::
+
+   glance.image_members.create(image_id, member_id)
+
+Remove a Share
+--------------
+Remove a shared image from a tenant::
+
+   glance.image_members.delete(image_id, member_id)
+
+List Sharings
+-------------
+Describe sharing permissions by image or tenant::
+
+   glance.image_members.list(image_id)
+
diff --git a/doc/source/index.rst b/doc/source/index.rst
index f33e8085..f4234fb3 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -15,6 +15,7 @@ In order to use the python api directly, you must first obtain an auth token and
                 f.write(chunk)
     >>> image.delete()
 
+For an API v2 example see also :doc:`apiv2`.
 
 Command-line Tool
 =================