(POOLER-37) Document HTTP responses

docs/API.md

@@ -19,6 +19,11 @@ Token-based authentication can be used when requesting or modifying VMs.  The `/
 
 Get a list of issued tokens.
 
+Return codes:
+* 200  OK
+* 401  when not authorized
+* 404  when config:auth not found or other error
+
 ```
 $ curl -u jdoe --url vmpooler.example.com/api/v1/token
 Enter host password for user 'jdoe':
@@ -36,6 +41,11 @@ Enter host password for user 'jdoe':
 
 Generate a new authentication token.
 
+Return codes:
+* 200  OK
+* 401  when not authorized
+* 404  when config:auth not found
+
 ```
 $ curl -X POST -u jdoe --url vmpooler.example.com/api/v1/token
 Enter host password for user 'jdoe':
@@ -51,6 +61,10 @@ Enter host password for user 'jdoe':
 
 Get information about an existing token (including associated VMs).
 
+Return codes:
+* 200  OK
+* 404  when config:auth or token not found
+
 ```
 $ curl --url vmpooler.example.com/api/v1/token/utpg2i2xswor6h8ttjhu3d47z53yy47y
 ```
@@ -75,6 +89,11 @@ $ curl --url vmpooler.example.com/api/v1/token/utpg2i2xswor6h8ttjhu3d47z53yy47y
 
 Delete an authentication token.
 
+Return codes:
+* 200  OK
+* 401  when not authorized
+* 404  when config:auth not found
+
 ```
 $ curl -X DELETE -u jdoe --url vmpooler.example.com/api/v1/token/utpg2i2xswor6h8ttjhu3d47z53yy47y
 Enter host password for user 'jdoe':
@@ -91,6 +110,9 @@ Enter host password for user 'jdoe':
 
 Retrieve a list of available VM pools.
 
+Return codes:
+* 200  OK
+
 ```
 $ curl --url vmpooler.example.com/api/v1/vm
 ```
@@ -103,10 +125,14 @@ $ curl --url vmpooler.example.com/api/v1/vm
 
 ##### POST /vm
 
-Useful for batch operations; post JSON (see format below), get back VMs.
+Useful for batch operations; post JSON (see format below), get back allocated VMs.
 
 If an authentication store is configured, an authentication token supplied via the `X-AUTH-TOKEN` HTTP header will modify a VM's default lifetime.  See the provided YAML configuration example, [vmpooler.yaml.example](vmpooler.yaml.example), and the 'token operations' section above for more information.
 
+Return codes:
+* 200  OK
+* 404  when sending invalid JSON in the request body or requesting an invalid VM pool name
+
 ```
 $ curl -d '{"debian-7-i386":"2","debian-7-x86_64":"1"}' --url vmpooler.example.com/api/v1/vm
 ```
@@ -132,6 +158,10 @@ $ curl -d '{"debian-7-i386":"2","debian-7-x86_64":"1"}' --url vmpooler.example.c
 
 Check-out a VM or VMs.
 
+Return codes:
+* 200  OK
+* 404  when sending invalid JSON in the request body or requesting an invalid VM pool name
+
 ```
 $ curl -d --url vmpooler.example.com/api/v1/vm/debian-7-i386
 ```
@@ -171,7 +201,11 @@ $ curl -d --url vmpooler.example.com/api/v1/vm/debian-7-i386+debian-7-i386+debia
 
 ##### GET /vm/<hostname>
 
-Query a checked-out VM.
+Query metadata information for a checked-out VM.
+
+Return codes:
+* 200  OK
+* 404  when requesting an invalid VM hostname
 
 ```
 $ curl --url vmpooler.example.com/api/v1/vm/pxpmtoonx7fiqg6
@@ -182,12 +216,14 @@ $ curl --url vmpooler.example.com/api/v1/vm/pxpmtoonx7fiqg6
   "pxpmtoonx7fiqg6": {
     "template": "centos-6-x86_64",
     "lifetime": 12,
-    "running": 3.1,
+    "running": 3,
+    "remaining": 9, 
     "state": "running",
     "tags": {
       "department": "engineering",
       "user": "jdoe"
     },
+    "ip": "192.168.0.1",
     "domain": "example.com"
   }
 }
@@ -208,6 +244,12 @@ Any modifications can be verified using the [GET /vm/<hostname>](#get-vmho
 
 If an authentication store is configured, an authentication token is required (via the `X-AUTH-TOKEN` HTTP header) to access this route.  See the provided YAML configuration example, [vmpooler.yaml.example](vmpooler.yaml.example), and the 'token operations' section above for more information.
 
+Return codes:
+* 200  OK
+* 401  when you need an auth token
+* 404  when requesting an invalid VM hostname
+* 400  when supplied PUT parameters fail validation
+
 ```
 $ curl -X PUT -d '{"lifetime":"2"}' --url vmpooler.example.com/api/v1/vm/fq6qlpjlsskycq6
 ```
@@ -230,6 +272,11 @@ $ curl -X PUT -d '{"tags":{"department":"engineering","user":"jdoe"}}' --url vmp
 
 Schedule a checked-out VM for deletion.
 
+Return codes:
+* 200  OK
+* 401  when you need an auth token
+* 404  when requesting an invalid VM hostname
+
 ```
 $ curl -X DELETE --url vmpooler.example.com/api/v1/vm/fq6qlpjlsskycq6
 ```
@@ -245,6 +292,11 @@ $ curl -X DELETE --url vmpooler.example.com/api/v1/vm/fq6qlpjlsskycq6
 
 Add an additional disk to a running VM.
 
+Return codes:
+* 202  OK
+* 401  when you need an auth token
+* 404  when requesting an invalid VM hostname or size is not an integer
+
 ````
 $ curl -X POST -H X-AUTH-TOKEN:a9znth9dn01t416hrguu56ze37t790bl --url vmpooler.example.com/api/v1/vm/fq6qlpjlsskycq6/disk/8
 ````
@@ -285,6 +337,11 @@ $ curl --url vmpooler.example.com/api/v1/vm/fq6qlpjlsskycq6
 
 Create a snapshot of a running VM.
 
+Return codes:
+* 202  OK
+* 401  when you need an auth token
+* 404  when requesting an invalid VM hostname
+
 ````
 $ curl -X POST -H X-AUTH-TOKEN:a9znth9dn01t416hrguu56ze37t790bl --url vmpooler.example.com/api/v1/vm/fq6qlpjlsskycq6/snapshot
 ````
@@ -322,6 +379,11 @@ $ curl --url vmpooler.example.com/api/v1/vm/fq6qlpjlsskycq6
 
 Revert a VM back to a snapshot.
 
+Return codes:
+* 202  OK
+* 401  when you need an auth token
+* 404  when requesting an invalid VM hostname or snapshot is not valid
+
 ````
 $ curl X POST -H X-AUTH-TOKEN:a9znth9dn01t416hrguu56ze37t790bl --url vmpooler.example.com/api/v1/vm/fq6qlpjlsskycq6/snapshot/n4eb4kdtp7rwv4x158366vd9jhac8btq
 ````
@@ -386,6 +448,12 @@ If there are empty pools, the "status" section will convey this:
   }
 ```
 
+The top level sections are: "capacity", "queue", "clone", "boot", "pools" and "status".
+If the query parameter 'view' is provided, it will be used to select which top level
+element to compute and return. Select them by specifying which one you want in a comma 
+separated list.
+For example `vmpooler.example.com/api/v1/status?view=capacity,boot`
+
 ##### GET /summary[?from=YYYY-MM-DD[&to=YYYY-MM-DD]]
 
 Returns a summary, or report, for the timespan between `from` and `to` (inclusive)
@@ -395,6 +463,11 @@ metrics, such as boot and cloning durations.
 Any omitted query parameter will default to now/today. A request without any
 parameters will result in the current day's summary.
 
+Return codes:
+* 200  OK
+* 400  Invalid date format or range
+
+
 ```
 $ curl --url vmpooler.example.com/api/v1/summary
 ```
@@ -486,6 +559,7 @@ $ curl --url vmpooler.example.com/api/v1/summary
 }
 ```
 
+
 ```
 $ curl -G -d 'from=2015-03-10' -d 'to=2015-03-11' --url vmpooler.example.com/api/v1/summary
 ```
@@ -550,15 +624,21 @@ $ curl -G -d 'from=2015-03-10' -d 'to=2015-03-11' --url vmpooler.example.com/api
 }
 ```
 
+You can also query only the specific top level section you want by including it after `summary/`.
+The valid sections are "boot", "clone" or "tag" eg. `vmpooler.example.com/api/v1/summary/boot/`.
+You can further drill-down the data by specifying the second level parameter to query eg
+`vmpooler.example.com/api/v1/summary/tag/created_by`
+
 #### Managing pool configuration via API <a name="poolconfig"></a>
 
 ##### GET /config
 
 Returns the running pool configuration
 
-Responses:
-* 200 - OK
-* 404 - No configuration found
+Return codes
+* 200  OK 
+* 400  No configuration found  
+
 ```
 $ curl https://vmpooler.example.com/api/v1/config
 ```