Adds OpenStack API Quick Start guide
* Update the index.html for the api site * Fix a missing trailing } in one example * Adds an example for using a token in the X-Auth-Token header Change-Id: I6e4fdd600fe8b4f575aa80d5fcaad68fbd5f407f
This commit is contained in:
annegentle
parent
2db72768e3
commit
8849614352
@ -7,37 +7,7 @@
|
||||
version="5.0"
|
||||
xml:id="openstack-api-quick-start">
|
||||
<title>OpenStack API Quick Start</title>
|
||||
<info>
|
||||
<!--<author>
|
||||
<personname>
|
||||
<firstname/>
|
||||
<surname/>
|
||||
</personname>
|
||||
<affiliation>
|
||||
<orgname>OpenStack</orgname>
|
||||
</affiliation>
|
||||
</author>-->
|
||||
<!--<copyright>
|
||||
<year>2010</year>
|
||||
<year>2011</year>
|
||||
<year>2012</year>
|
||||
<holder>OpenStack LLC</holder>
|
||||
</copyright>
|
||||
<releaseinfo>Diablo</releaseinfo>
|
||||
<productname>OpenStack Compute, Identity, and Image Services</productname>
|
||||
<pubdate>2011-02-13</pubdate>
|
||||
<legalnotice role="apache2">
|
||||
<annotation>
|
||||
<remark>Remaining licensing details are filled in by the template.</remark>
|
||||
</annotation>
|
||||
</legalnotice>
|
||||
<abstract>
|
||||
<para>OpenStack™ projects offer RESTful APIs for manipulating and retrieving objects in
|
||||
the cloud. This guide provides examples for sending REST requests using the Compute
|
||||
API v1.1 and Identity API v2.0. </para>
|
||||
</abstract>-->
|
||||
</info>
|
||||
<?dbhtml stop-chunking?>
|
||||
<xi:include href="api-quick-start.xml"/>
|
||||
<xi:include href="api-quick-start-intro.xml"/>
|
||||
<xi:include href="cli-uses.xml"/>
|
||||
</chapter>
|
||||
|
||||
@ -1,143 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<section 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_Quick_Start"
|
||||
version="5.0">
|
||||
<title>OpenStack API Quick Start</title>
|
||||
<para>The OpenStack system has several key projects that are
|
||||
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, 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">
|
||||
|
||||
<title>OpenStack API Introduction</title>
|
||||
<para>This page covers the basics for talking to your OpenStack
|
||||
cloud through the Compute API after authorizing with the
|
||||
Identity Service API. You can then build a cloud 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 the <link xlink:href="http://docs.openstack.org/api/openstack-identity-service/2.0/content/">Identity Service 2.0 specification</link> published at
|
||||
<link xlink:href="http://docs.openstack.org/api"
|
||||
>docs.openstack.org/api</link>. </para></section>
|
||||
<section xml:id="Getting-Credentials-a00665"><title>Getting Credentials</title><para>Credentials are a combination of your username, 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 well as your tenant
|
||||
identifier so you can generate authorization tokens. 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>
|
||||
<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 are with (the "tenant" in auth-speak). </para>
|
||||
<para><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'</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></listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Repeatedly send API requests with that token in 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>
|
||||
</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'
|
||||
</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>
|
||||
{
|
||||
"access": {
|
||||
"serviceCatalog": [
|
||||
{
|
||||
"endpoints": [
|
||||
{
|
||||
"adminURL": "https://nova-api.trystack.org:9774/v1.1/1",
|
||||
"internalURL": "https://nova-api.trystack.org:9774/v1.1/1",
|
||||
"publicURL": "https://nova-api.trystack.org:9774/v1.1/1",
|
||||
"region": "RegionOne"
|
||||
}
|
||||
],
|
||||
"name": "nova",
|
||||
"type": "compute"
|
||||
},
|
||||
{
|
||||
"endpoints": [
|
||||
{
|
||||
"adminURL": "https://GLANCE_API_IS_NOT_DISCLOSED/v1.1/1",
|
||||
"internalURL": "https://GLANCE_API_IS_NOT_DISCLOSED/v1.1/1",
|
||||
"publicURL": "https://GLANCE_API_IS_NOT_DISCLOSED/v1.1/1",
|
||||
"region": "RegionOne"
|
||||
}
|
||||
],
|
||||
"name": "glance",
|
||||
"type": "image"
|
||||
},
|
||||
{
|
||||
"endpoints": [
|
||||
{
|
||||
"adminURL": "https://nova-api.trystack.org:5443/v2.0",
|
||||
"internalURL": "https://keystone.trystack.org:5000/v2.0",
|
||||
"publicURL": "https://keystone.trystack.org:5000/v2.0",
|
||||
"region": "RegionOne"
|
||||
}
|
||||
],
|
||||
"name": "keystone",
|
||||
"type": "identity"
|
||||
}
|
||||
],
|
||||
"token": {
|
||||
"expires": "2012-02-15T19:32:21",
|
||||
"id": "5df9d45d-d198-4222-9b4c-7a280aa35666",
|
||||
"tenant": {
|
||||
"id": "1",
|
||||
"name": "admin"
|
||||
}
|
||||
},
|
||||
"user": {
|
||||
"id": "14",
|
||||
"name": "annegentle",
|
||||
"roles": [
|
||||
{
|
||||
"id": "2",
|
||||
"name": "Member",
|
||||
"tenantId": "1"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
</programlisting></para></section>
|
||||
<section xml:id="Sending-Requests-to-API-a09879">
|
||||
<title>Sending Requests to the API</title>
|
||||
<para>You have a couple of options for sending requests to OpenStack through an API.
|
||||
Developers and testers may prefer to use cURL, the command-line tool from <link
|
||||
xlink:href="http://curl.haxx.se/">http://curl.haxx.se/</link>. With cURL you can
|
||||
send HTTP requests and receive responses back from the command line. </para>
|
||||
<para>If you like to use a more graphical interface, the REST client for Firefox also works
|
||||
well for testing and trying out commands, see <link
|
||||
xlink:href="https://addons.mozilla.org/en-US/firefox/addon/restclient/"
|
||||
>https://addons.mozilla.org/en-US/firefox/addon/restclient/</link>. You can also
|
||||
download and install rest-client, a Java application to test RESTful web services, from
|
||||
<link xlink:href="http://code.google.com/p/rest-client/"
|
||||
>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>
|
||||
</section>
|
||||
|
||||
|
||||
</section>
|
||||
@ -171,6 +171,16 @@
|
||||
»</a></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><a href=
|
||||
"http://docs.openstack.org/api/quick-start/content/">
|
||||
OpenStack API Quick Start</a></td>
|
||||
|
||||
<td><a href=
|
||||
"http://docs.openstack.org/api/quick-start/content/"
|
||||
class="roundedButton">Read »</a></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><a href=
|
||||
"http://docs.openstack.org/api/openstack-compute/programmer/content/">
|
||||
|
||||
Loading…
Reference in New Issue
Block a user