Skip to content
Browse files

Updating API docs

  • Loading branch information...
1 parent 364c1cf commit b6dd1eb6f049a2b6dd5cec663b8cbe19b00d973a Lance committed Jan 20, 2011
View
2 app/controllers/api_controller.rb
@@ -20,7 +20,7 @@ class ApiController < ApplicationController
helper_method :steamcannon_api_version
def steamcannon_api_version
- '0.1'
+ '0.2'
end
def index
View
46 docs/en-US/src/main/docbook/api.xml
@@ -20,10 +20,10 @@
</para>
<para>
SteamCannon's <acronym>API</acronym> is implemented using
- <acronym>HATEOS</acronym> (Hypermedia as the Engine of Application State)
+ <acronym>HATEOAS</acronym> (Hypermedia as the Engine of Application State)
where all a client needs to know is the entry point URL. Subsequent
access to objects within the system is made possible by URLs returned in
- the server response. For more information about REST and HATEOS, please
+ the server response. For more information about REST and HATEOAS, please
see the reference below.
<itemizedlist>
<listitem>
@@ -41,11 +41,11 @@
</para>
<section>
- <title>Deltacloud Endpoint</title>
+ <title>DeltaCloud Endpoint</title>
<para>
- The primary function of the SteamCannon API in this nascent version is
- to expose a user- and environment-specific Deltacloud endpoint which
- may be used to start and stop SteamCannon machine instances within a
+ SteamCannon uses DeltaCloud under the covers to communicate with
+ the cloud. Our API exposes a DeltaCloud-compatible endpoint which may
+ be used to start and stop SteamCannon machine instances within a
SteamCannon environment. Through this Deltacloud endpoint, clients have
access to instances, images, hardware profiles and realms. These
entities are abstractions of specific cloud-based objects, allowing
@@ -77,7 +77,7 @@
<section>
<title>Server Responses</title>
<para>
- All server responses from the API will be in XML format. In the event
+ All server responses from the API are in XML format. In the event
that a client attempts to access a resource which does not exist or for
which the user is not authorized, the server will issue an HTTP 404
(Not Found) error code in response. Creation of new objects, for example
@@ -98,8 +98,9 @@
<code>&lt;link&gt;</code> elements. The <code>rel</code> attribute
provides the name of the collection. A <code>GET</code> request to the
URL in the <code>href</code> attribute provides access to the collection
- itself. As you can see, the API endpoint for version 0.1 contains a
- single collection &mdash; environments.
+ itself. The API endpoint contains links to collections of the SteamCannon
+ objects, including <code>environments</code>, <code>artifacts</code>
+ <code>cloud_profiles</code> and <code>platforms</code>.
</para>
</section>
<section>
@@ -118,10 +119,8 @@
<title>Environment Collections</title>
<para>
By sending a GET request to the endpoint's <code>environments</code>
- link, you can access a collection of all environments available. The
- server returns a list of the authenticated user's environments as
- <code>&lt;environment&gt;</code> elements, each containing
- <code>name</code> and <code>href</code> attributes as shown below.
+ link, you can access a collection of all environments available to the
+ authenticated user as shown below.
<screen><xi:include href="api/environments.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></screen>
</para>
</section>
@@ -130,7 +129,7 @@
<para>
Clients may access a single <code>&lt;environment&gt;</code> using an
<code>href</code> from the environments collection. For example
- <code>http://try.steamcannon.org/environments/12</code> provides
+ <code>http://try.steamcannon.org/environments/2</code> provides
identifying information about the environment, as well as information
about the current state, and a link to a Deltacloud API endpoint
for the environment.
@@ -170,7 +169,6 @@
no instances are running the environment will be considered
<code>stopped</code>
</para>
- </section>
<section>
<title>preserve_storage_volumes</title>
<para>
@@ -179,11 +177,29 @@
on shutdown.
</para>
</section>
+ </section>
+ <section>
+ <title>cloud_profile</title>
+ <para>
+ This is information about the cloud the environment is configured
+ to run on, including the cloud and provider names as well as any
+ storage buckets created at runtime.
+ </para>
+ </section>
+ <section>
+ <title>deployments</title>
+ <para>If any artifacts have been deployed to this environment
+ they will appear here as links to the deployment object.</para>
+ </section>
<section>
<title>metadata</title>
<para>Any metadata associated with this environment.</para>
</section>
<section>
+ <title>actions</title>
+ <para>TODO: Fill this in</para>
+ </section>
+ <section>
<title>link</title>
<para>
The link tag provides access to the environment-specific Deltacloud
View
6 docs/en-US/src/main/docbook/api/endpoint.xml
@@ -1,3 +1,7 @@
-<api version='0.1'>
+<api version='0.2'>
<link href='http://try.steamcannon.org/environments' rel='environments' />
+ <link href='http://try.steamcannon.org/artifacts' rel='artifacts' />
+ <link href='http://try.steamcannon.org/cloud_profiles' rel='cloud_profiles' />
+ <link href='http://try.steamcannon.org/platforms' rel='platforms' />
</api>
+
View
32 docs/en-US/src/main/docbook/api/environment.xml
@@ -1,15 +1,27 @@
-<environment href='http://localhost:8080/environments/15'>
- <name>Staging, 2-tier</name>
- <owner>lanceball@gmail.com</owner>
- <created>2010-11-04 22:26:03 UTC</created>
- <updated>2010-12-10 22:02:01 UTC</updated>
- <current_state>stopped</current_state>
+<environment href='http://try.steamcannon.org/environments/2'>
+ <name>Test API</name>
+ <owner>lball@redhat.com</owner>
+ <created>2011-01-17 21:56:48 UTC</created>
+ <updated>2011-01-17 22:33:16 UTC</updated>
+ <current_state>stopping</current_state>
<preserve_storage_volumes>false</preserve_storage_volumes>
+ <cloud_profile href='http://try.steamcannon.org/cloud_profiles/1' id='1'>
+ <cloud_name>ec2</cloud_name>
+ <provider>us-east-1</provider>
+ <name>Default EC2</name>
+ <artifacts_bucket>SteamCannonArtifacts_d1c38d12aafb7d886f65f56321a7bf94318caa45</artifacts_bucket>
+ <clustering_bucket>SteamCannonEnvironments_d1c38d12aafb7d886f65f56321a7bf94318caa45</clustering_bucket>
+ </cloud_profile>
+ <deployments href='http://try.steamcannon.org/environments/2/deployments'>
+ </deployments>
<metadata>
-
+ jboss_as_admin_useruseradminpasswordf7f0ea78b216337c7d1f91eaf4239f
</metadata>
- <link
- href='http://try.steamcannon.org/environments/15/deltacloud'
- rel='deltacloud_endpoint' />
+ <actions>
+ <link href='http://try.steamcannon.org/environments/2/start' rel='start' />
+ <link href='http://try.steamcannon.org/environments/2/clone' rel='clone' />
+ <link href='http://try.steamcannon.org/environments/2?_method=delete' rel='delete' />
+ </actions>
+ <link href='http://try.steamcannon.org/environments/2/deltacloud' rel='deltacloud_endpoint' />
</environment>
View
66 docs/en-US/src/main/docbook/api/environments.xml
@@ -1,19 +1,57 @@
<environments>
- <environment
- href='http://try.steamcannon.org/environments/16'
- name='my development env'>
+ <environment href='http://try.steamcannon.org/environments/1'>
+ <name>2 Tier Test</name>
+ <owner>lball@redhat.com</owner>
+ <created>2010-12-13 17:39:12 UTC</created>
+ <updated>2011-01-18 13:59:06 UTC</updated>
+ <current_state>stopped</current_state>
+ <preserve_storage_volumes>false</preserve_storage_volumes>
+ <cloud_profile href='http://try.steamcannon.org/cloud_profiles/1' id='1'>
+ <cloud_name>ec2</cloud_name>
+ <provider>us-east-1</provider>
+ <name>Default EC2</name>
+ <artifacts_bucket>SteamCannonArtifacts_d1c38d12aafb7d886f65f56321a7bf94318caa45</artifacts_bucket>
+ <clustering_bucket>SteamCannonEnvironments_d1c38d12aafb7d886f65f56321a7bf94318caa45</clustering_bucket>
+ </cloud_profile>
+ <deployments href='http://try.steamcannon.org/environments/1/deployments'>
+ <link href='http://try.steamcannon.org/environments/1/deployments/1' rel='deployment' />
+ <link href='http://try.steamcannon.org/environments/1/deployments/2' rel='deployment' />
+ </deployments>
+ <metadata>
+ jboss_as_admin_useruseradminpassword69ffbe285c8e803fd880b22d73b27b
+ </metadata>
+ <actions>
+ <link href='http://try.steamcannon.org/environments/1/start' rel='start' />
+ <link href='http://try.steamcannon.org/environments/1/clone' rel='clone' />
+ <link href='http://try.steamcannon.org/environments/1?_method=delete' rel='delete' />
+ </actions>
+ <link href='http://try.steamcannon.org/environments/1/deltacloud' rel='deltacloud_endpoint' />
</environment>
- <environment
- href='http://try.steamcannon.org/environments/14'
- name='test platform'>
- </environment>
- <environment
- href='http://try.steamcannon.org/environments/12'
- name='Staging, 2-tier'>
- </environment>
- <environment
- href='http://try.steamcannon.org/environments/17'
- name='Production, 3-tier'>
+ <environment href='http://try.steamcannon.org/environments/2'>
+ <name>Test API</name>
+ <owner>lball@redhat.com</owner>
+ <created>2011-01-17 21:56:48 UTC</created>
+ <updated>2011-01-17 22:33:16 UTC</updated>
+ <current_state>stopping</current_state>
+ <preserve_storage_volumes>false</preserve_storage_volumes>
+ <cloud_profile href='http://try.steamcannon.org/cloud_profiles/1' id='1'>
+ <cloud_name>ec2</cloud_name>
+ <provider>us-east-1</provider>
+ <name>Default EC2</name>
+ <artifacts_bucket>SteamCannonArtifacts_d1c38d12aafb7d886f65f56321a7bf94318caa45</artifacts_bucket>
+ <clustering_bucket>SteamCannonEnvironments_d1c38d12aafb7d886f65f56321a7bf94318caa45</clustering_bucket>
+ </cloud_profile>
+ <deployments href='http://try.steamcannon.org/environments/2/deployments'>
+ </deployments>
+ <metadata>
+ jboss_as_admin_useruseradminpasswordf7f0ea78b216337c7d1f91eaf4239f
+ </metadata>
+ <actions>
+ <link href='http://try.steamcannon.org/environments/2/start' rel='start' />
+ <link href='http://try.steamcannon.org/environments/2/clone' rel='clone' />
+ <link href='http://try.steamcannon.org/environments/2?_method=delete' rel='delete' />
+ </actions>
+ <link href='http://try.steamcannon.org/environments/2/deltacloud' rel='deltacloud_endpoint' />
</environment>
</environments>

0 comments on commit b6dd1eb

Please sign in to comment.
Something went wrong with that request. Please try again.