Merge pull request #401 from matrix-org/rav/underscore_api_convention

Document convention of using underscores in APIs

specification/client_server_api.rst

@@ -72,6 +72,16 @@ MUST be encoded as UTF-8. Clients are authenticated using opaque
 ``access_token`` strings (see `Client Authentication`_ for details), passed as a
 query string parameter on all requests.
 
+The names of the API endponts for the HTTP transport follow a convention of
+using underscores to separate words (for example ``/delete_devices``). The key
+names in JSON objects passed over the API also follow this convention.
+
+.. NOTE::
+   There are a few historical exceptions to this rule, such as
+   ``/createRoom``. A future version of this specification will address the
+   inconsistency.
+
+
 Any errors which occur at the Matrix API level MUST return a "standard error
 response". This is a JSON object which looks like: