api-ref method verification for os-cells

Confirm and correct list methods and response codes in os-cells.

This is mostly just checking, correcting and adding methods, but
in the process of doing that it became clear that there was quite
a bit missing so several TODO notes have been left in place so that
the next stages of work are a bit more obvious.

* 405 has been removed everywhere as we don't send that response
* 400 badRequest is required anywhere, as that's what you'll get if
  tenant_id does not match the context's project_id
* 503 does not happen as there's no application controlled proxying
  in this api
* the URL for listing cells with details was incorrect
* the example response for cells with details was an empty list,
  this is now a todo suggesting an as yet non-existent file
* capacities was not listed, now is
* not clear what capacities really are, so a TODO
* creating a new cell (via POST) was not there, so that is now added
  as a method
* for that POST, request and response bodies, parameters currently a
  TODO
* Update (PUT) and DELETE of a cell has been added, but details are TODO

Part of bp:api-ref-in-rst

Change-Id: I3f123f821820e5a5a4deff61fb716d43dc486142

api-ref/source/os-cells.inc

@@ -1,9 +1,9 @@
 .. -*- rst -*-
-.. needs:method_verification
 .. needs:parameter_verification
 .. needs:example_verification
 .. needs:body_verification
 
+
 ==============================
  Cells (os-cells, capacities)
 ==============================
@@ -20,8 +20,17 @@ Lists cells.
 
 Normal response codes: 200
 
-Error response codes: computeFault(400, 500), serviceUnavailable(503), badRequest(400),
-unauthorized(401), forbidden(403), badMethod(405), itemNotFound(404), NotImplemented(501)
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+NotImplemented(501)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - tenant_id: tenant_id
+
+.. TODO(cdent): How do we indicate optionality of a URI parameter?
 
 Response
 --------
@@ -31,26 +40,71 @@ Response
 .. literalinclude:: ../../doc/api_samples/os-cells/cells-list-resp.json
    :language: javascript
 
+Create Cell
+===========
+
+.. rest_method:: POST /os-cells
+
+Create a new cell.
+
+Normal response code: 200
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+NotImplemented(501)
+
+.. TODO(cdent): need to figure out body stuff for request and response
+
+.. TODO(cdent): need a sample
+
+Capacities
+==========
+
+.. rest_method:: GET /os-cells/capacities
+
+Retrieve capacities.
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+NotImplemented(501)
+
+.. TODO(cdent): Need to do more digging, no idea.
+
 List Cells With Details
 =======================
 
-.. rest_method:: GET /os-cells
+.. rest_method:: GET /os-cells/detail
 
-Lists cells with details.
+Lists cells with details of capabilities.
 
 Normal response codes: 200
 
-Error response codes: computeFault(400, 500), serviceUnavailable(503), badRequest(400),
-unauthorized(401), forbidden(403), badMethod(405), itemNotFound(404), NotImplemented(501)
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+NotImplemented(501)
 
 Response
 --------
 
 **Example List Cells With Details: JSON response**
 
-.. literalinclude:: ../../doc/api_samples/os-cells/cells-list-empty-resp.json
+.. TODO(cdent): This sample was initially list with an empty list of cells.
+   The newly listed sample does not yet exist.
+
+.. TODO(cdent):  literal-include: ../../doc/api_samples/os-cells/cells-list-details-resp.json
    :language: javascript
 
+Info For This Cell
+==================
+
+.. rest_method:: GET /os-cells/info
+
+Retrieve info about the current cell.
+
+Normal response code: 200
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+NotImplemented(501)
+
+.. TODO(cdent): this is weird, data is stuctured entirely differently.
+
 Show Cell Data
 ==============
 
@@ -60,8 +114,8 @@ Shows data for a cell.
 
 Normal response codes: 200
 
-Error response codes: computeFault(400, 500), serviceUnavailable(503), badRequest(400),
-unauthorized(401), forbidden(403), badMethod(405), itemNotFound(404), NotImplemented(501)
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404), NotImplemented(501)
 
 Request
 -------
@@ -78,6 +132,33 @@ Response
 .. literalinclude:: ../../doc/api_samples/os-cells/cells-get-resp.json
    :language: javascript
 
+Update a Cell
+=============
+
+.. rest_method:: PUT /os-cells/{cell_od}
+
+
+Update an existing cell.
+
+Normal response code: 200
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404), NotImplemented(501)
+
+.. TODO(cdent): Figure out what's going on here.
+
+Delete a Cell
+=============
+
+.. rest_method:: DELETE /os-cells/{cell_id}
+
+Remove a cell.
+
+Normal response code: 200
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404), NotImplemented(501)
+
 Show Cell Capacities
 ====================
 
@@ -85,10 +166,12 @@ Show Cell Capacities
 
 Shows capacities for a cell.
 
+.. TODO(cdent): What's a capacities.
+
 Normal response codes: 200,501
 
-Error response codes: computeFault(400, 500), serviceUnavailable(503), badRequest(400),
-unauthorized(401), forbidden(403), badMethod(405), itemNotFound(404), NotImplemented(501)
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404), NotImplemented(501)
 
 Request
 -------