diff --git a/docs/src/glazier-manual/src/docbkx/figures/api_workflow.png b/docs/src/glazier-manual/src/docbkx/figures/api_workflow.png new file mode 100755 index 0000000..e1e19f8 Binary files /dev/null and b/docs/src/glazier-manual/src/docbkx/figures/api_workflow.png differ diff --git a/docs/src/glazier-manual/src/docbkx/glazier-manual.xml b/docs/src/glazier-manual/src/docbkx/glazier-manual.xml index 8f0cde8..9994936 100644 --- a/docs/src/glazier-manual/src/docbkx/glazier-manual.xml +++ b/docs/src/glazier-manual/src/docbkx/glazier-manual.xml @@ -19,7 +19,10 @@ xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg" xmlns:m="http://www.w3.org/1998/Math/MathML" - xmlns:html="http://www.w3.org/1999/xhtml" version="5.0" status="DRAFT"> + xmlns:html="http://www.w3.org/1999/xhtml" version="5.0" status="DRAFT" + xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd + http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd +http://docbook.org/ns/docbook " xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> Glazier Project Documentation @@ -110,9 +113,9 @@ - + Architecture -
+
Architecture @@ -158,4 +161,285 @@ + + API Specification + + + + Revision Date + Summary of Changes + + + + + February 4, 2013 + + + + Initial document creation + + + + + + February 22, 2013 + + + + Enhance API with latest architecture + changes + + + + + + + March 06, 2013 + + + + Fix specification according to remarks + from Dmitry Teselkin + + + + + + + +
+ Introduction + Glazier Service API is a programmatic interface used for interaction + with Glazier. Other interaction + mechanisms like Glazier Dashboard or Glazier CLI should use API as underlying + protocol for interaction. + + + + For detailed information about entities and terms used in this document, please refer first to + . + + + Environment + + Environment is a set of logically related Services managed by a single tenant. Environment + defines Windows environment boundaries. + + Services within single Environment may comprise some complex configuration while Services + in different Environments are always independent from one another. Each Environment is + associated with single OpenStack project (tenant). + + + + + Service + + Service is building block of Windows environment. Service is a set of one or more Virtual + Machines sharing a common purpose and configured together. Each service belongs to a single + Environment and single Service Type. + + Services are comprised from one or more Service Units. + + + + Service Type + + Service type is definition for describing set of features exposed by service. + + + + Service Unit + + Service Units are the actual Windows Server VMs instantiated by OpenStack and then + configured according to its Service Type (this may also correspond to one of predefined + Windows Server roles). + + + + + Service Metadata + + Service Metadata is a JSON-encoded definition of Environment, its Services and their + Service Units along with all their attributes. Service Metadata may describe both current + and the intended state of the Environment. + + + + + Session + + All changes to environment done in scope of Session. After all changes to Environment + state are accumulated, changes actually are applied only after session is deployed. + + + + +
+
+ Return codes and errors + All REST API calls return the natural HTTP response codes for the operations, e.g. a successful GET + returns a HTTP 200, a successful PUT returns a HTTP 201, a GET for a non-existent entity returns HTTP + 404, unauthorized operations return HTTP 401 or HTTP 403, internal errors return HTTP 500. + +
+
+ Response of POSTs and PUTs + All POST and PUT requests by convention should return the created object (in the case of POST, with a + generated ID) as if it was requested by GET. + +
+
+ Authentication + All requests include a Keystone authentication token header (X-Auth-Token). Clients must authenticate + with Keystone before interacting with the Glazier service. + +
+
+ Workflow +
+ Sample Workflow + + + + + + + + +
+ Let’s review a sample workflow (series of API calls) for creating new Environment with Active + Directory Service deployment: + + + POST /environments/ - Creating new Environment + + + POST /environments/id/configure – Creating new configuration session for Environment + + + + POST /environments/id/activeDirectory – Creating new ActiveDirectory service + + + POST /environments/id/sessions/session_id/deploy – Saving and deploying changes + + + +
+
+ API +
+ Environment API + This section describes API calls for Environment management. + + Environment Object + + + + + + + Attribute + Type + Description + + + + + id + GUID + Unique ID + + + name + string + User-friendly name + + + created + datetime + Creation date and time in ISO format + + + updated + datetime + Modification date and time in ISO format + + + tenant_id + GUID + Open Stack tenant id + + + status + string + Deployment status: draft, pending, inprogress, finished + + + +
+
+ Get a List of existing Environments +
+ Call + + + + + + + + + Method + URI + Description + + + + + GET + /environments + Get a list of existing Environments + + + +
+
+
+ Payload + None +
+
+ Returns + This call returns list of environments. Only the basic properties are returned. For details see “Get Environment Detailed Information”: + + + + +
+
+
+
+