summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSerg Melikyan <smelikyan@mirantis.com>2013-04-05 18:46:23 +0400
committerSerg Melikyan <smelikyan@mirantis.com>2013-04-05 18:46:23 +0400
commit107d3fbeb26bef6de160b310999008f33d317ace (patch)
treee631ed890364ea57b942a470405ddb21c569b177
parentef341be381ff303c156f84ace310581874c398aa (diff)
Added part of API Specification
-rwxr-xr-xdocs/src/glazier-manual/src/docbkx/figures/api_workflow.pngbin0 -> 26028 bytes
-rw-r--r--docs/src/glazier-manual/src/docbkx/glazier-manual.xml290
2 files changed, 287 insertions, 3 deletions
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
--- /dev/null
+++ b/docs/src/glazier-manual/src/docbkx/figures/api_workflow.png
Binary files 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 @@
19 xmlns:xi="http://www.w3.org/2001/XInclude" 19 xmlns:xi="http://www.w3.org/2001/XInclude"
20 xmlns:svg="http://www.w3.org/2000/svg" 20 xmlns:svg="http://www.w3.org/2000/svg"
21 xmlns:m="http://www.w3.org/1998/Math/MathML" 21 xmlns:m="http://www.w3.org/1998/Math/MathML"
22 xmlns:html="http://www.w3.org/1999/xhtml" version="5.0" status="DRAFT"> 22 xmlns:html="http://www.w3.org/1999/xhtml" version="5.0" status="DRAFT"
23 xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
24 http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd
25http://docbook.org/ns/docbook " xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
23 <title>Glazier Project Documentation</title> 26 <title>Glazier Project Documentation</title>
24 <info> 27 <info>
25 <author> 28 <author>
@@ -110,9 +113,9 @@
110 </itemizedlist> 113 </itemizedlist>
111 </section> 114 </section>
112 </chapter> 115 </chapter>
113 <chapter> 116 <chapter id="architecture">
114 <title>Architecture</title> 117 <title>Architecture</title>
115 <figure xml:id="keeroarchitecture"> 118 <figure xml:id="glazierarchitecture">
116 <title>Architecture</title> 119 <title>Architecture</title>
117 <mediaobject> 120 <mediaobject>
118 <imageobject role="fo"> 121 <imageobject role="fo">
@@ -158,4 +161,285 @@
158 </itemizedlist> 161 </itemizedlist>
159 </para> 162 </para>
160 </chapter> 163 </chapter>
164 <chapter>
165 <title>API Specification</title>
166 <informaltable rules="all">
167 <thead>
168 <tr>
169 <td align="center" colspan="1">Revision Date</td>
170 <td align="center" colspan="4">Summary of Changes</td>
171 </tr>
172 </thead>
173 <tbody>
174 <tr>
175 <td colspan="1" align="center">February 4, 2013</td>
176 <td colspan="4">
177 <itemizedlist spacing="compact">
178 <listitem>
179 <para>Initial document creation</para>
180 </listitem>
181 </itemizedlist>
182 </td>
183 </tr>
184 <tr>
185 <td colspan="1" align="center">February 22, 2013</td>
186 <td colspan="4">
187 <itemizedlist spacing="compact">
188 <listitem>
189 <para>Enhance API with latest architecture
190 changes
191 </para>
192 </listitem>
193 </itemizedlist>
194 </td>
195 </tr>
196 <tr>
197 <td colspan="1" align="center">March 06, 2013</td>
198 <td colspan="4">
199 <itemizedlist spacing="compact">
200 <listitem>
201 <para>Fix specification according to remarks
202 from Dmitry Teselkin
203 </para>
204 </listitem>
205 </itemizedlist>
206 </td>
207 </tr>
208 </tbody>
209 </informaltable>
210 <section>
211 <title>Introduction</title>
212 <para>Glazier Service API is a programmatic interface used for interaction
213 with Glazier. Other interaction
214 mechanisms like Glazier Dashboard or Glazier CLI should use API as underlying
215 protocol for interaction.
216 </para>
217
218 <glossary>
219 <para>For detailed information about entities and terms used in this document, please refer first to
220 <xref
221 linkend="architecture"/>.
222 </para>
223 <glossentry>
224 <glossterm>Environment</glossterm>
225 <glossdef>
226 <para>Environment is a set of logically related Services managed by a single tenant. Environment
227 defines Windows environment boundaries.
228 </para>
229 <para>Services within single Environment may comprise some complex configuration while Services
230 in different Environments are always independent from one another. Each Environment is
231 associated with single OpenStack project (tenant).
232 </para>
233 </glossdef>
234 </glossentry>
235 <glossentry>
236 <glossterm>Service</glossterm>
237 <glossdef>
238 <para>Service is building block of Windows environment. Service is a set of one or more Virtual
239 Machines sharing a common purpose and configured together. Each service belongs to a single
240 Environment and single Service Type.
241 </para>
242 <para>Services are comprised from one or more Service Units.</para>
243 </glossdef>
244 </glossentry>
245 <glossentry>
246 <glossterm>Service Type</glossterm>
247 <glossdef>
248 <para>Service type is definition for describing set of features exposed by service.</para>
249 </glossdef>
250 </glossentry>
251 <glossentry>
252 <glossterm>Service Unit</glossterm>
253 <glossdef>
254 <para>Service Units are the actual Windows Server VMs instantiated by OpenStack and then
255 configured according to its Service Type (this may also correspond to one of predefined
256 Windows Server roles).
257 </para>
258 </glossdef>
259 </glossentry>
260 <glossentry>
261 <glossterm>Service Metadata</glossterm>
262 <glossdef>
263 <para>Service Metadata is a JSON-encoded definition of Environment, its Services and their
264 Service Units along with all their attributes. Service Metadata may describe both current
265 and the intended state of the Environment.
266 </para>
267 </glossdef>
268 </glossentry>
269 <glossentry>
270 <glossterm>Session</glossterm>
271 <glossdef>
272 <para>All changes to environment done in scope of Session. After all changes to Environment
273 state are accumulated, changes actually are applied only after session is deployed.
274 </para>
275 </glossdef>
276 </glossentry>
277 </glossary>
278 </section>
279 <section>
280 <title>Return codes and errors</title>
281 <para>All REST API calls return the natural HTTP response codes for the operations, e.g. a successful GET
282 returns a HTTP 200, a successful PUT returns a HTTP 201, a GET for a non-existent entity returns HTTP
283 404, unauthorized operations return HTTP 401 or HTTP 403, internal errors return HTTP 500.
284 </para>
285 </section>
286 <section>
287 <title>Response of POSTs and PUTs</title>
288 <para>All POST and PUT requests by convention should return the created object (in the case of POST, with a
289 generated ID) as if it was requested by GET.
290 </para>
291 </section>
292 <section>
293 <title>Authentication</title>
294 <para>All requests include a Keystone authentication token header (X-Auth-Token). Clients must authenticate
295 with Keystone before interacting with the Glazier service.
296 </para>
297 </section>
298 <section>
299 <title>Workflow</title>
300 <figure xml:id="api_workflow">
301 <title>Sample Workflow</title>
302 <mediaobject>
303 <imageobject role="fo">
304 <imagedata fileref="figures/api_workflow.png"
305 contentwidth="5in"/>
306 </imageobject>
307 <imageobject role="html">
308 <imagedata fileref="figures/api_workflow.png"/>
309 </imageobject>
310 </mediaobject>
311 </figure>
312 <para>Let’s review a sample workflow (series of API calls) for creating new Environment with Active
313 Directory Service deployment:
314 <orderedlist spacing="compact">
315 <listitem>
316 <para>POST /environments/ - Creating new Environment</para>
317 </listitem>
318 <listitem>
319 <para>POST /environments/id/configure – Creating new configuration session for Environment
320 </para>
321 </listitem>
322 <listitem>
323 <para>POST /environments/id/activeDirectory – Creating new ActiveDirectory service</para>
324 </listitem>
325 <listitem>
326 <para>POST /environments/id/sessions/session_id/deploy – Saving and deploying changes</para>
327 </listitem>
328 </orderedlist>
329 </para>
330 </section>
331 <section>
332 <title>API</title>
333 <section>
334 <title>Environment API</title>
335 <para>This section describes API calls for Environment management.</para>
336 <table frame='all'>
337 <title>Environment Object</title>
338 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
339 <colspec colnum="1" colname="col1" colwidth="1*"/>
340 <colspec colnum="2" colname="col2" colwidth="1*"/>
341 <colspec colnum="3" colname="col3" colwidth="4*"/>
342 <thead>
343 <row>
344 <entry>Attribute</entry>
345 <entry>Type</entry>
346 <entry>Description</entry>
347 </row>
348 </thead>
349 <tbody>
350 <row>
351 <entry>id</entry>
352 <entry>GUID</entry>
353 <entry>Unique ID</entry>
354 </row>
355 <row>
356 <entry>name</entry>
357 <entry>string</entry>
358 <entry>User-friendly name</entry>
359 </row>
360 <row>
361 <entry>created</entry>
362 <entry>datetime</entry>
363 <entry>Creation date and time in ISO format</entry>
364 </row>
365 <row>
366 <entry>updated</entry>
367 <entry>datetime</entry>
368 <entry>Modification date and time in ISO format</entry>
369 </row>
370 <row>
371 <entry>tenant_id</entry>
372 <entry>GUID</entry>
373 <entry>Open Stack tenant id</entry>
374 </row>
375 <row>
376 <entry>status</entry>
377 <entry>string</entry>
378 <entry>Deployment status: draft, pending, inprogress, finished</entry>
379 </row>
380 </tbody>
381 </tgroup>
382 </table>
383 <section>
384 <title>Get a List of existing Environments</title>
385 <section>
386 <title>Call</title>
387 <table frame='all'>
388 <title> </title>
389 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
390 <colspec colnum="1" colname="col1" colwidth="1*"/>
391 <colspec colnum="2" colname="col2" colwidth="4*"/>
392 <colspec colnum="3" colname="col3" colwidth="4*"/>
393 <thead>
394 <row>
395 <entry>Method</entry>
396 <entry>URI</entry>
397 <entry>Description</entry>
398 </row>
399 </thead>
400 <tbody>
401 <row>
402 <entry>GET</entry>
403 <entry>/environments</entry>
404 <entry>Get a list of existing Environments</entry>
405 </row>
406 </tbody>
407 </tgroup>
408 </table>
409 </section>
410 <section>
411 <title>Payload</title>
412 <para>None</para>
413 </section>
414 <section>
415 <title>Returns</title>
416 <para>This call returns list of environments. Only the basic properties are returned. For details see “Get Environment Detailed Information”:
417 <programlisting>
418 <![CDATA[
419 {
420 "environments": [
421 {
422 "id": "0ce373a477f211e187a55404a662f968",
423 "name": "dc1",
424 "created": "2010-11-30T03:23:42Z",
425 "updated": "2010-11-30T03:23:44Z",
426 "tenant_id": "0849006f7ce94961b3aab4e46d6f229a"
427 },
428 {
429 "id": "c697bd2429304820a928d145aa42af59",
430 "name": "dc2",
431 "created": "2010-11-30T03:23:42Z",
432 "updated": "2010-11-30T03:23:44Z",
433 "tenant_id": "0849006f7ce94961b3aab4e46d6f229a"
434 }
435 ]
436}
437 ]]>
438 </programlisting>
439 </para>
440 </section>
441 </section>
442 </section>
443 </section>
444 </chapter>
161</book> 445</book>