243 lines
16 KiB
XML
243 lines
16 KiB
XML
<?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/<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/<account></para>
|
|
<para>HEAD /v1.0/<account></para></section>
|
|
<section><title>Storage Container Services</title>
|
|
<para>GET /v1.0/<account>/<container></para>
|
|
<para>HEAD /v1.0/<account>/<container></para>
|
|
<para>PUT /v1.0/<account>/<container></para>
|
|
<para>DELETE /v1.0/<account>/<container></para>
|
|
</section>
|
|
<section><title>Storage Object Services</title>
|
|
<para>GET /v1.0/<account>/<container>/<object></para>
|
|
<para>HEAD /v1.0/<account>/<container>/<object></para>
|
|
<para>PUT /v1.0/<account>/<container>/<object></para>
|
|
<para>DELETE /v1.0/<account>/<container>/<object></para>
|
|
<para>POST /v1.0/<account>/<container>/<object></para>
|
|
</section></section>
|
|
</chapter>
|