openstack/api-site
Code Issues Proposed changes

Edits to the API quick start to:

Browse Source 
- update Google Analytics code
- link to the CLI guide rather than embed
- offer a way to retrieve tenantId
- demonstrate with curl a command with X-Auth-Token

Change-Id: Ia3e0eb0331983845058136f09f8ede46a8885737
This commit is contained in:
annegentle
2012-11-15 15:28:58 -06:00
parent 26f09e393b
commit d2e433d9f2
4 changed files with 115 additions and 275 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
api-quick-start/pom.xml
View File

@@ -49,7 +49,7 @@
<plugin>
<groupId>com.rackspace.cloud.api</groupId>
<artifactId>clouddocs-maven-plugin</artifactId>
<version>1.4.0</version>
<version>1.5.1</version>
<executions>
<!--<execution>
<id>goal1</id>
@@ -74,7 +74,7 @@
<enableDisqus>1</enableDisqus>
<disqusShortname>os-apiquickstart</disqusShortname>
<enableGoogleAnalytics>1</enableGoogleAnalytics>
<googleAnalyticsId>UA-17511903-6</googleAnalyticsId>
<googleAnalyticsId>UA-17511903-1</googleAnalyticsId>
<!--<generateToc>
appendix toc,title
article/appendix nop

242
api-quick-start/src/docbkx/api-examples.xml
View File

@@ -1,242 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xml:id="Compute_API_Examples"
version="5.0">
<title>OpenStack API Examples</title>
<para>Here are some examples of the basic API commands you can send to an OpenStack deployment
containing Compute, the Image Service, with a running Identity Server. In the "service
catalog" that is returned when you get a token, you can find the endpoint URLs that you use
for these API commands. For example this public URL entry in the service catalog offers the
URL for the Image Service, code-named glance: </para>
<para>
<literallayout class="monospaced">"publicURL": "http://55.51.11.198:9292/v1.1/9"}], "type": "image", "name": "glance"</literallayout>
</para>
<para>For the Compute API, you see a service of type compute, code-named "nova" such as: </para>
<para>
<literallayout class="monospaced">"publicURL": "http://55.51.11.198:8774/v1.1/9"}], "type": "compute", "name": "nova"</literallayout>
</para>
<para>With these publicURLs in hand, you can now use curl commands for these endpoints and send
API requests. The following sections offer walk-throughs of common API commands. Refer to
<link xlink:href="http://docs.openstack.org/api">docs.openstack.org/api</link> for a
full reference of all API commands for these services.</para>
<para>Many of the APIs support query parameters. For example, to navigate the collection, the parameters limit and marker can be set in the URI. </para>
<variablelist>
<title>Query Parameters</title>
<varlistentry>
<term><code>limit</code></term>
<listitem>
<para>For an integer value <inlineequation>
<mathphrase><emphasis>n</emphasis></mathphrase>
</inlineequation>, limits the number of results to at most <inlineequation>
<mathphrase><emphasis>n</emphasis></mathphrase>
</inlineequation> values.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>marker</code></term>
<listitem>
<para>Given a string value <inlineequation>
<mathphrase><emphasis>x</emphasis></mathphrase>
</inlineequation>, return object names greater in value than the specified
marker.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><code>format</code></term>
<listitem>
<para>Specify either <code>json</code> or
<code>xml</code> to return the respective
serialized response. For example, append
<programlisting>?format=json</programlisting>onto
a query to inform the service that you want the
information serialized in JSON when it is returned
to you.</para>
</listitem>
</varlistentry>
</variablelist>
<para>At this time, a <code>prefix</code> query parameter is not supported at the account
level for Object Storage.</para>
<section xml:id="Compute-API-Server-Flavor-Examples-a10234">
<title>Compute API Flavor Examples</title>
<para><emphasis role="bold">GET /v1.1/flavors</emphasis></para>
<para>Gives you a listing of flavors available, which are combinations of disk space, memory
and CPU capacity bundled together as resources for virtual machines.</para>
<para>Curl example: </para>
<literallayout class="monospaced">curl -D - -H "X-Auth-Token: 3017813d-deca-4764-aa33-9ab59a283ba6" -X 'GET' -v
http://demo.rcb.me:8774/v1.1/9/flavors
{"flavors": [{"id": 3, "links": [
{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/3", "rel": "self"},
{"href": "http://demo.rcb.me:8774/9/flavors/3", "rel": "bookmark"}], "name": "m1.medium"},
{"id": 4, "links": [{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/4", "rel": "self"},
{"href": "http://demo.rcb.me:8774/9/flavors/4", "rel": "bookmark"}], "name": "m1.large"},
{"id": 1, "links": [{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/1", "rel": "self"},
{"href": "http://demo.rcb.me:8774/9/flavors/1", "rel": "bookmark"}], "name": "m1.tiny"},
{"id": 5, "links": [{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/5", "rel": "self"},
{"href": "http://demo.rcb.me:8774/9/flavors/5", "rel": "bookmark"}], "name": "m1.xlarge"},
{"id": 2, "links": [{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/2", "rel": "self"},
{"href": "http://demo.rcb.me:8774/9/flavors/2", "rel": "bookmark"}], "name": "m1.small"}]}</literallayout>
<para><emphasis role="bold">GET /v1.1/flavors/&lt;id></emphasis></para>
<para>Gives you more detail about the specific flavor. </para>
<para>Curl example:</para>
<para>curl -D - -H "X-Auth-Token: 3017813d-deca-4764-aa33-9ab59a283ba6" -X 'GET' -v
http://demo.rcb.me:8774/v1.1/9/flavors/5</para>
<para>{"flavor": {"rxtx_quota": 0, "name": "m1.xlarge", "links": [{"href":
"http://demo.rcb.me:8774/v1.1/9/flavors/5", "rel": "self"}, {"href":
"http://demo.rcb.me:8774/9/flavors/5", "rel": "bookmark"}], "ram": 16384, "vcpus": 8,
"rxtx_cap": 0, "swap": 0, "disk": 160, "id": 5}}</para>
<para><emphasis role="bold">GET /v1.1/flavors/detail</emphasis></para>
<para>Gives you details on all the available instance types (flavors). </para>
<para>Curl example: </para>
<para>curl -D - -H "X-Auth-Token: 3017813d-deca-4764-aa33-9ab59a283ba6" -X 'GET' -v
http://demo.rcb.me:8774/v1.1/9/flavors/detail</para>
<para>{"flavors": [{"rxtx_quota": 0, "name": "m1.medium", "links": [{"href":
"http://demo.rcb.me:8774/v1.1/9/flavors/3", "rel": "self"}, {"href":
"http://demo.rcb.me:8774/9/flavors/3", "rel": "bookmark"}], "ram": 4096, "vcpus": 2,
"rxtx_cap": 0, "swap": 0, "disk": 40, "id": 3}, {"rxtx_quota": 0, "name": "m1.large",
"links": [{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/4", "rel": "self"}, {"href":
"http://demo.rcb.me:8774/9/flavors/4", "rel": "bookmark"}], "ram": 8192, "vcpus": 4,
"rxtx_cap": 0, "swap": 0, "disk": 80, "id": 4}, {"rxtx_quota": 0, "name": "m1.tiny",
"links": [{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/1", "rel": "self"}, {"href":
"http://demo.rcb.me:8774/9/flavors/1", "rel": "bookmark"}], "ram": 512, "vcpus": 1,
"rxtx_cap": 0, "swap": 0, "disk": 0, "id": 1}, {"rxtx_quota": 0, "name": "m1.xlarge",
"links": [{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/5", "rel": "self"}, {"href":
"http://demo.rcb.me:8774/9/flavors/5", "rel": "bookmark"}], "ram": 16384, "vcpus": 8,
"rxtx_cap": 0, "swap": 0, "disk": 160, "id": 5}, {"rxtx_quota": 0, "name": "m1.small",
"links": [{"href": "http://demo.rcb.me:8774/v1.1/9/flavors/2", "rel": "self"}, {"href":
"http://demo.rcb.me:8774/9/flavors/2", "rel": "bookmark"}], "ram": 2048, "vcpus": 1,
"rxtx_cap": 0, "swap": 0, "disk": 20, "id": 2}]}</para>
</section>
<section xml:id="Compute-API-Server-Examples-a09234">
<title>Compute API Server Information Examples</title>
<para><emphasis role="bold">GET /v1.1/servers</emphasis></para>
<para>Gives you a listing of active servers under your account and tenant authorized with a
particular token. If there are no servers running, you see just "{"servers": []}"
returned but still get a 200 OK response.</para>
<para>Curl example: </para>
<literallayout class="monospaced">curl -D - -H "X-Auth-Token: 3017813d-deca-4764-aa33-9ab59a283ba6" -X 'GET' -v http://host.na.me:8774/v1.1/9/servers</literallayout>
<para><emphasis role="bold">GET /v1.1/servers/detail</emphasis></para>
<para>Shows details of all the active servers currently running under your account. </para>
<para>Curl example:</para>
<para>curl -D - -H "X-Auth-Token: 3017813d-deca-4764-aa33-9ab59a283ba6" -X 'GET' -v
http://demo.rcb.me:8774/v1.1/9/servers/detail </para>
<para>POST /v1.1/servers</para>
<para>GET /v1.1/servers/<emphasis role="italic">id</emphasis></para>
<para>PUT /v1.1/servers/<emphasis role="italic">id</emphasis></para>
<para>DELETE /v1.1/servers/<emphasis role="italic">id</emphasis></para></section>
<section xml:id="Compute-API-Server-Action-Examples-a08234">
<title>Compute API Server Actions Examples</title>
<para>POST /v1.1/servers/id/reboot</para>
<para>POST /v1.1/servers/id/rebuild</para>
<para>POST /v1.1/servers/id/resize?</para>
<para>POST /v1.1/servers/id/confirmResize?</para>
<para>POST /v1.1/servers/id/revertResize?</para>
</section>
<section xml:id="Compute-API-Server-Extensions-Examples-a09744">
<title>Compute API Extensions Examples</title>
<para>GET /v1.1/extensions</para>
<para>Shows the installed extensions to the API, which enable more requests and actions for
the Compute server. </para>
<para>Curl example: </para>
<literallayout class="monospaced">curl -D - -H "X-Auth-Token: 8528179e-0d07-44e9-b972-7427336c94cb" -X 'GET' -v http://demo.rcb.me:8774/v1.1/9/extensions</literallayout>
<literallayout class="monospaced">{"extensions": [{"updated": "2011-06-29T00:00:00+00:00",
"name": "Hosts", "links": [],
"namespace": "http://docs.openstack.org/ext/hosts/api/v1.1",
"alias": "os-hosts", "description": "Host administration"},
{"updated": "2011-03-25T00:00:00+00:00",
"name": "Volumes", "links": [], "namespace": "http://docs.openstack.org/ext/volumes/api/v1.1", "alias": "os-volumes", "description": "Volumes support"},
{"updated": "2011-05-25 16:12:21.656723",
"name": "Admin Controller", "links": [], "namespace": "http:TODO/", "alias": "ADMIN", "description": "The Admin API Extension"},
{"updated": "2011-08-08T00:00:00+00:00",
"name": "Quotas", "links": [], "namespace": "http://docs.openstack.org/ext/quotas-sets/api/v1.1", "alias": "os-quota-sets", "description": "Quotas management support"},
{"updated": "2011-08-18T00:00:00+00:00",
"name": "Rescue", "links": [], "namespace": "http://docs.openstack.org/ext/rescue/api/v1.1", "alias": "os-rescue", "description": "Instance rescue mode"},
{"updated": "2011-06-09T00:00:00+00:00",
"name": "Multinic", "links": [], "namespace": "http://docs.openstack.org/ext/multinic/api/v1.1", "alias": "NMN", "description": "Multiple network support"},
{"updated": "2011-09-14T00:00:00+00:00",
"name": "FlavorExtraData", "links": [], "namespace": "http://docs.openstack.org/ext/flavor_extra_data/api/v1.1", "alias": "os-flavor-extra-data", "description": "Provide additional data for flavors"},
{"updated": "2011-07-21T00:00:00+00:00",
"name": "SecurityGroups", "links": [], "namespace": "http://docs.openstack.org/ext/securitygroups/api/v1.1", "alias": "security_groups", "description": "Security group support"},
{"updated": "2011-06-23T00:00:00+00:00",
"name": "FlavorExtraSpecs", "links": [], "namespace": "http://docs.openstack.org/ext/flavor_extra_specs/api/v1.1", "alias": "os-flavor-extra-specs", "description": "Instance type (flavor) extra specs"},
{"updated": "2011-07-19T00:00:00+00:00",
"name": "Createserverext", "links": [], "namespace": "http://docs.openstack.org/ext/createserverext/api/v1.1", "alias": "os-create-server-ext", "description": "Extended support to the Create Server v1.1 API"},
{"updated": "2011-08-08T00:00:00+00:00",
"name": "Keypairs", "links": [], "namespace": "http://docs.openstack.org/ext/keypairs/api/v1.1", "alias": "os-keypairs", "description": "Keypair Support"},
{"updated": "2011-08-25T00:00:00+00:00",
"name": "VSAs", "links": [], "namespace": "http://docs.openstack.org/ext/vsa/api/v1.1", "alias": "zadr-vsa", "description": "Virtual Storage Arrays support"},
{"updated": "2011-08-19T00:00:00+00:00",
"name": "SimpleTenantUsage", "links": [], "namespace": "http://docs.openstack.org/ext/os-simple-tenant-usage/api/v1.1", "alias": "os-simple-tenant-usage", "description": "Simple tenant usage extension"},
{"updated": "2011-08-24T00:00:00+00:00",
"name": "VolumeTypes", "links": [], "namespace": "http://docs.openstack.org/ext/volume_types/api/v1.1", "alias": "os-volume-types", "description": "Volume types support"},
{"updated": "2011-08-17T00:00:00+00:00",
"name": "VirtualInterfaces", "links": [], "namespace": "http://docs.openstack.org/ext/virtual_interfaces/api/v1.1", "alias": "virtual_interfaces", "description": "Virtual interface support"},
{"updated": "2011-06-16T00:00:00+00:00",
"name": "Floating_ips", "links": [], "namespace": "http://docs.openstack.org/ext/floating_ips/api/v1.1", "alias": "os-floating-ips", "description": "Floating IPs support"}]}</literallayout>
</section>
<section xml:id="Image-API-Examples"><title>Image API Examples</title>
<para>GET /images</para>
<para>Curl example:</para>
<para>
<literallayout class="monospaced">curl -D - -H "X-Auth-Token: 469dbbaa-40f2-418a-aafe-1abcf03113f7" -X 'GET' -v http://demo.rcb.me:9292/v1/images
{"images": [
{"name": "uec-oneiric", "container_format": "ami", "disk_format": "ami", "checksum": "f8b72b5d643152c1beaa5d15555c9353", "id": 7, "size": 1476395008},
{"name": "uec-oneiric-kernel", "container_format": "aki", "disk_format": "aki", "checksum": "0577116c1df5e3d39aa33aee53a64e2b", "id": 6, "size": 4731376},
{"name": "uec-natty", "container_format": "ami", "disk_format": "ami", "checksum": "1808dfa4fb62f3804707eb0beeb7fa03", "id": 5, "size": 1476395008},
{"name": "uec-natty-kernel", "container_format": "aki", "disk_format": "aki", "checksum": "af6261015c5466ad672c3ed18cecae04", "id": 4, "size": 4594816},
{"name": "tty", "container_format": "ami", "disk_format": "ami", "checksum": "10047a119149e08fb206eea89832eee0", "id": 3, "size": 25165824},
{"name": "tty-ramdisk", "container_format": "ari", "disk_format": "ari", "checksum": "2d222d406f3ed30e03ed44123c33cba6", "id": 2, "size": 5882349},
{"name": "tty-kernel", "container_format": "aki", "disk_format": "aki", "checksum": "3ed2965d3f8d877a3ee3e061fd648e9a", "id": 1, "size": 4404752}]}</literallayout>
</para>
<para>GET /images/details</para>
<para>GET /images/<emphasis role="italic">id</emphasis></para>
<para>POST /images</para>
<para>PUT /images/<emphasis role="italic">id</emphasis> (with metadata headers)</para>
<para>GET /images/<emphasis role="italic">id</emphasis>/members (knowing who can view an
image)</para>
<para>PUT /images/<emphasis role="italic">id</emphasis>/members (replaces membership list
for image)</para>
<para>GET /shared-images/tenant-id (shares an image with a tenant, or makes it
public)</para>
<para>DELETE /images/1/members/tenant1 (revokes tenant's access to an image)</para></section>
<section xml:id="Identity-API-Examples"><title>Identity API Examples</title>
<para>POST /v2.0/tokens</para>
<programlisting>
curl -X 'POST' -v http://host.na.me:5000/v2.0/tokens -d '{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}' -H 'Content-type: application/json'
</programlisting>
</section>
<section xml:id="Object-API-Examples"><title>Object API Examples</title>
<section><title>Storage Account Services</title>
<para>GET /v1.0/&lt;account&gt;</para>
<para>HEAD /v1.0/&lt;account&gt;</para></section>
<section><title>Storage Container Services</title>
<para>GET /v1.0/&lt;account&gt;/&lt;container&gt;</para>
<para>HEAD /v1.0/&lt;account&gt;/&lt;container&gt;</para>
<para>PUT /v1.0/&lt;account&gt;/&lt;container&gt;</para>
<para>DELETE /v1.0/&lt;account&gt;/&lt;container&gt;</para>
</section>
<section><title>Storage Object Services</title>
<para>GET /v1.0/&lt;account&gt;/&lt;container&gt;/&lt;object&gt;</para>
<para>HEAD /v1.0/&lt;account&gt;/&lt;container&gt;/&lt;object&gt;</para>
<para>PUT /v1.0/&lt;account&gt;/&lt;container&gt;/&lt;object&gt;</para>
<para>DELETE /v1.0/&lt;account&gt;/&lt;container&gt;/&lt;object&gt;</para>
<para>POST /v1.0/&lt;account&gt;/&lt;container&gt;/&lt;object&gt;</para>
</section></section>
</chapter>

118
api-quick-start/src/docbkx/api-quick-start-intro.xml
View File

@@ -8,7 +8,7 @@
separate installations but can work together depending on your
cloud needs: OpenStack Compute, OpenStack Object Storage,
OpenStack Identity Service, and OpenStack Image Store. With
the TryStack OpenStack installation, the OpenStack Compute,
the <link xlink:href="http://www.trystack.org/">TryStack</link> OpenStack installation, the OpenStack Compute,
OpenStack Identity, and OpenStack Image Store projects are all
working together in the background of the installation. </para>
<section xml:id="Openstack-API-Concepts-a09234">
@@ -20,8 +20,8 @@
by launching images and assigning metadata to instances,
all through the API. For an API reference of all the
possible commands, see the <link
xlink:href="http://docs.openstack.org/api/openstack-compute/1.1/content/"
>OpenStack Compute API 1.1 specification</link> and
xlink:href="http://docs.openstack.org/api/openstack-compute/2/content/"
>OpenStack Compute API v2 specification</link> and
the <link
xlink:href="http://docs.openstack.org/api/openstack-identity-service/2.0/content/"
>Identity Service 2.0 specification</link> published
@@ -30,12 +30,12 @@
</section>
<section xml:id="Getting-Credentials-a00665">
<title>Getting Credentials</title>
<para>Credentials are a combination of your username,
<para>Credentials are a combination of your user name,
password, and what tenant (or project) your cloud is
running under. You only need to generate an additional
token if you are interacting with your cloud directly with
API endpoints, and not with a client. Your cloud
administrator can give you a username and a password as
administrator can give you a user name and a password as
well as your tenant identifier so you can generate
authorization tokens. You can also get the tenant ID from
the Dashboard URLs, for example
@@ -44,49 +44,52 @@
<para>These tokens are typically good for 24 hours, and when
the token expires, you will find out with a 401
(Unauthorized) error and can request another token
programmatically. The general workflow goes something like
this: </para>
programmatically. The general work flow goes something
like this: </para>
<orderedlist>
<listitem>
<para>Begin API requests by asking for an
authorization token from the endpoint your cloud
administrator gave you, typically
http://hostname:port/v2.0/tokens. You send your
username, password, and what group or account you
user name, password, and what group or account you
are with (the "tenant" in auth-speak). </para>
<para><programlisting>curl -k -X 'POST' -v https://nova-api.trystack.org:5443/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'</programlisting></para>
<para><programlisting language="bash" role="gutter: false">curl -k -X 'POST' -v https://nova-api.trystack.org:5443/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'</programlisting></para>
</listitem>
<listitem>
<para>The server returns a response in which the
24-hours token is contained. Use that token to
send API requests with the X-Auth-Token included
as an header field.</para>
<para><programlisting>curl -k -D - -H "X-Auth-Token: 7d2f63fd-4dcc-4752-8e9b-1d08f989cc00" -X 'GET' -v https://nova-api.trystack.org:9774/v1.1/296/extensions -H 'Content-type: application/json' </programlisting></para>
<para><programlisting language="bash" role="gutter: false">curl -k -D - -H "X-Auth-Token: 7d2f63fd-4dcc-4752-8e9b-1d08f989cc00" -X 'GET' -v https://nova-api.trystack.org:9774/v1.1/296/extensions -H 'Content-type: application/json' </programlisting></para>
</listitem>
<listitem>
<para>Repeatedly send API requests with that token in
the x-auth-token header until either: 1) the job's
the X-Auth-Token header until either: 1) the job's
done or 2) you get a 401 (Unauthorized) code in
return. </para>
</listitem>
<listitem>
<para>Request a token again when you get a 401
response until the script's job is done.</para>
response or until the script's job is done.</para>
</listitem>
</orderedlist>
<para>For a typical OpenStack deployment running the Identity
Service you can request a token with this command in
cURL:<programlisting>
$ curl -X 'POST' -v https://nova-api.trystack.org:5443/v2.0/tokens -d '{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'
Service you can request a token with this command in cURL
if you know your
tenantId:<programlisting language="bash" role="gutter: false">
$ curl -X 'POST' -v
https://nova-api.trystack.org:5443/v2.0/tokens -d
'{"auth":{"passwordCredentials":{"username": "joecool", "password":"coolword"}, "tenantId":"5"}}' -H 'Content-type: application/json'
</programlisting></para>
<para>In return, you should get a 200 OK response with a token
in the form of "id":
"cd427a33-bb4a-4079-a6d7-0ae148bdeda9" and an expiration
date 24 hours from now. Here's what it looks like:</para>
<para>
<programlisting>
<programlisting language="bash" role="gutter: false">
{
"access": {
"serviceCatalog": [
@@ -147,9 +150,61 @@ $ curl -X 'POST' -v https://nova-api.trystack.org:5443/v2.0/tokens -d '{"auth":{
]
}
}
}
</programlisting></para>
} </programlisting></para>
<para>If you don't know your tenantId, you can send a request
with an empty tenantId, such as this JSON example:</para>
<programlisting language="bash" role="gutter: false">
'{"auth":{"passwordCredentials":{"username": "usern4me", "password":"passwerd"}, "tenantId":""}}'
</programlisting>
<para>Then, with the auth token that returns, fill in a request using the X-Auth-Token header as an authentication to get your tenantId:</para>
<programlisting>curl -H "X-Auth-Token:6de6d45d-d198-4222-9b4c-7a280aa24999" http://arm.trystack.org:5000/v2.0/tenants</programlisting>
<para>In return, you get a list of
tenants:<programlisting language="bash" role="gutter: false">{
"tenants_links": [],
"tenants": [
{
"enabled": "true",
"description": "usern4me",
"name": "usern4me",
"id": "tenantnnnnnn"
}
]
}</programlisting></para>
<para>Use the resulting token to make a new POST request
containing the tenantId so you can retrieve
endpoints:</para>
<programlisting language="bash" role="gutter: false">curl -k -X 'POST' -v http://arm.trystack.org:5000/v2.0/tokens -d
'{"auth":{"passwordCredentials":{"username": "usern4me", "password":"passwerd"}, "tenantId":"tenantnnnnnn"}}' -H 'Content-type: application/json'</programlisting>
<para> The resulting JSON contains a list of endpoints, for
example:
<programlisting language="bash" role="gutter: false">{
"endpoints": [
{
"adminURL": "http://10.225.0.8:8774/v2/tenantnnnnnn",
"region": "Calxeda-AUS1",
"internalURL": "http://10.225.0.8:8774/v2/tenantnnnnnn",
"publicURL": "http://208.123.85.197:8774/v2/tenantnnnnnn"
}
],
"endpoints_links": [],
"type": "compute",
"name": "nova"
}</programlisting></para>
<para>In addition, you can see a valid token matched to your
user and
tenantId:<programlisting language="bash" role="gutter: false">{
"access": {
"token": {
"expires": "2012-10-31T17: 13: 12Z",
"id": "new_token***",
"tenant": {
"enabled": true,
"id": "tenantnnnnnn",
"name": "usern4me",
"description": "usern4me"
}
}
}</programlisting></para>
</section>
<section xml:id="Sending-Requests-to-API-a09879">
<title>Sending Requests to the API</title>
@@ -171,6 +226,31 @@ $ curl -X 'POST' -v https://nova-api.trystack.org:5443/v2.0/tokens -d '{"auth":{
>http://code.google.com/p/rest-client/</link>. </para>
<para>You need to generate a token as shown above if you use
cURL or a REST client. </para>
<para>It's also recommended that you install and use a
Command-Line-Client (CLI) such as python-novaclient, which
is documented in <link xlink:href="http://docs.openstack.org/cli/quick-start/content/index.html">CLI guide</link>. </para>
<para>Here's an example of curl commands that can check your list of servers. </para>
<programlisting>curl -v -H "X-Auth-Token:<replaceable>tokengoeshere</replaceable>" http://208.123.85.197:8774/v2/<replaceable>tenantnnnnnn</replaceable>/servers</programlisting>
<para>Here's what you get in return if you have a running server.</para>
<programlisting>{
"servers": [
{
"id": "server***",
"links": [
{
"href": "http://208.123.85.197:8774/v2/tenantnnnnnn/servers/server***",
"rel": "self"
},
{
"href": "http://208.123.85.197:8774/tenantnnnnnn/servers/server***",
"rel": "bookmark"
}
],
"name": "Staging Server"
}
]
}</programlisting>
</section>

26
api-quick-start/src/docbkx/cli-uses.xml
View File

@@ -6,19 +6,21 @@
version="5.0">
<title>Setting Up python-novaclient</title>
<para>For more serious scripting work, you can use a client like the python-novaclient or openstack-compute clients. The python-novaclient implements the Compute 1.1 API while the openstack-compute client works against the Rackspace Cloud Servers public cloud which is the OpenStack Compute 1.0 API. You only need a username and password to use the python-novaclient tool. </para>
<para>For more serious scripting work, you can use a client like the
python-novaclient client. The python-novaclient implements
Compute API through a command-line interface. You only need a
user name and password to use the python-novaclient tool. </para>
<para>Installing the python-novaclient gives you a <code>nova</code> shell command that enables
Compute API interactions from the command line. You install the client, and then provide
your username and password, set as environment variables for convenience, and then you
your user name and password, set as environment variables for convenience, and then you
can have the ability to send commands to your cloud on the command-line.</para>
<para>To install python-novaclient, grab the stable/nova version
like so. </para>
<programlisting>
<programlisting language="bash" role="gutter: false">
$ pip install -e git+https://github.com/openstack/python-novaclient.git#egg=python-novaclient
</programlisting>
<para>Here are more detailed install instructions including how to
source your credentials.</para>
<xi:include href="../../../cli-guide/src/nova_cli_install.xml" />
<para>The <link xlink:href="http://docs.openstack.org/cli/quick-start/content/index.html">CLI guide</link> offers more detailed install
instructions including how to source your credentials.</para>
<section xml:id="Listing-Images-a09140"><title>Listing Images</title><para>Before you can go about the business of building your cloud, you
want to know what images are available to you by asking
@@ -28,7 +30,7 @@ $ pip install -e git+https://github.com/openstack/python-novaclient.git#egg=pyth
before using your favorite image to create a new instance
in the cloud. To get the list of images, their names,
status, and ID, use this command:
<programlisting>
<programlisting language="bash" role="gutter: false">
$ nova image-list
+----+--------------------------------------+--------+--------+
@@ -47,7 +49,7 @@ $ nova image-list
<para>You also need to know the ID of the flavor
To get the list of flavors, their names,
status, and ID, use this command:</para>
<programlisting>
<programlisting language="bash" role="gutter: false">
$ nova flavor-list
+----+-----------+-----------+------+-----------+------+-------+-------------+
@@ -81,7 +83,7 @@ $ nova flavor-list
instance.</para>
</note></para>
<para>
<programlisting>
<programlisting language="bash" role="gutter: false">
$ nova boot --flavor=2 --image=13 testserver
+-----------+--------------------------------------+
@@ -103,7 +105,7 @@ $ nova flavor-list
</programlisting>
</para>
<para>Now, you can view this server in your new cloud by using the nova list
command:<programlisting>
command:<programlisting language="bash" role="gutter: false">
$ nova list
+------+------------+--------+--------------------------------+
| ID | Name | Status | Networks |
@@ -116,7 +118,7 @@ $ nova list
<para>To view all the information about a particular server, use
<code>nova show</code> with the ID of the server that
you got from the nova list command.</para>
<programlisting>
<programlisting language="bash" role="gutter: false">
$ nova show 1805
+-----------------+----------------------------------------------------------+
@@ -142,5 +144,5 @@ $ nova show 1805
Use the -meta option with a key=value pair, where you can make up the string for both the
key and the value. For example, you could add a description and also the creator of the
server.
<programlisting>$ nova boot testserver --meta description='Use for testing purposes' --meta creator=joecool</programlisting></para>
<programlisting language="bash" role="gutter: false">$ nova boot --flavor=2 --image=13 testserver --meta description='Use for testing purposes' --meta creator=joecool</programlisting></para>
</section></section>