Update coding document to mention direct REST calls

Now that we've got glance and swift done and have started on neutron,
let's update the doc to tell people that it's the way forward.

Change-Id: I16f7ae58f5ae280bc4b1533f62bf3e3a09dbaeb0

doc/source/coding.rst

@@ -56,22 +56,32 @@ Exceptions
 All underlying client exceptions must be captured and converted to an
 `OpenStackCloudException` or one of its derivatives.
 
-Client Calls
+REST Calls
 ============
 
-All underlying client calls (novaclient, swiftclient, etc.) must be
-wrapped by a Task object.
+All interactions with the cloud should be done with direct REST using
+the appropriate `keystoneauth1.adapter.Adapter`. See Glance and Swift
+calls for examples.
 
 Returned Resources
 ==================
 
-Complex objects returned to the caller must be a dict type. The
-methods `obj_to_dict()` or `obj_list_to_dict()` should be used for this.
+Complex objects returned to the caller must be a `munch.Munch` type. The
+`shade._adapter.Adapter` class makes resources into `munch.Munch`.
 
-As of this writing, those two methods are returning Munch objects, which help
-to maintain backward compatibility with a time when shade returned raw
-objects. Munch allows the returned resource to act as *both* an object
-and a dict.
+All objects should be normalized. It is shade's purpose in life to make
+OpenStack consistent for end users, and this means not trusting the clouds
+to return consistent objects. There should be a normalize function in
+`shade/_normalize.py` that is applied to objects before returning them to
+the user. See :doc:`model` for further details on object model requirements.
+
+Fields should not be in the normalization contract if we cannot commit to
+providing them to all users.
+
+Fields should be renamed in normalization to be consistent with
+the rest of shade. For instance, nothing in shade exposes the legacy OpenStack
+concept of "tenant" to a user, but instead uses "project" even if the
+cloud uses tenant.
 
 Nova vs. Neutron
 ================
@@ -90,6 +100,10 @@ Tests
 
 - New API methods *must* have unit tests!
 
+- New unit tests should only mock at the REST layer using `requests_mock`.
+  Any mocking of shade itself or of legacy client libraries should be
+  considered legacy and to be avoided.
+
 - Functional tests should be added, when possible.
 
 - In functional tests, always use unique names (for resources that have this