Update rpc_api docs with example version update

Update the rpc api devref docs to include an example of what a change
that includes a minor version increment looks like.  I hope this will
help clarify for people what all is included in an API change that
requires a version bump.

Part of blueprint rpc-docs-and-namespaces.

Change-Id: I9c53d3518b200412701b19958d7cbf1ed03d643e

diff --git a/doc/source/devref/rpc_api.rst b/doc/source/devref/rpc_api.rst
index 44be1cd44c6b8c6c8cb565a00346e751b14d0f0b..15a800746e1d2d49bbc4a88d664c7487e4d4fb47 100644 (file)
--- a/doc/source/devref/rpc_api.rst
+++ b/doc/source/devref/rpc_api.rst
@@ -83,14 +83,76 @@ It is possible to bump the major version number and drop some code only needed
 for backwards compatibility.  For more information about how to do that, see
 https://wiki.openstack.org/wiki/RpcMajorVersionUpdates.
 
+Example Change
+--------------
+
+As an example minor API change, let's assume we want to add a new parameter to
+my_remote_method_2.  First, we add the argument on the server side.  To be
+backwards compatible, the new argument must have a default value set so that the
+interface will still work even if the argument is not supplied.  Also, the
+interface's minor version number must be incremented.  So, the new server side
+code would look like this:
+
+::
+
+  from oslo import messaging
+
+
+  class ServerAPI(object):
+
+      target = messaging.Target(version='1.2')
+
+      def my_remote_method(self, context, arg1, arg2):
+          return 'foo'
+
+      def my_remote_method_2(self, context, arg1, arg2=None):
+          if not arg2:
+              # Deal with the fact that arg2 was not specified if needed.
+          return 'bar'
+
+We can now update the client side to pass the new argument.  The client must
+also specify that version '1.2' is required for this method call to be
+successful.  The updated client side would look like this:
+
+::
+
+  from oslo import messaging
+
+  from neutron.common import rpc as n_rpc
+
+
+  class ClientAPI(object):
+      """Client side RPC interface definition.
+
+      API version history:
+          1.0 - Initial version
+          1.1 - Added my_remote_method_2
+          1.2 - Added arg2 to my_remote_method_2
+      """
+
+      def __init__(self, topic):
+          target = messaging.Target(topic=topic, version='1.0')
+          self.client = n_rpc.get_client(target)
+
+      def my_remote_method(self, context, arg1, arg2):
+          cctxt = self.client.prepare()
+          return cctxt.call(context, 'my_remote_method', arg1=arg1, arg2=arg2)
+
+      def my_remote_method_2(self, context, arg1, arg2):
+          cctxt = self.client.prepare(version='1.2')
+          return cctxt.call(context, 'my_remote_method_2',
+                            arg1=arg1, arg2=arg2)
+
 Neutron RPC APIs
 ================
 
 As discussed before, RPC APIs are defined in two parts: a client side and a
-server side.  Several of these pairs exist in the Neutron code base.
+server side.  Several of these pairs exist in the Neutron code base.  The code
+base is being updated with documentation on every rpc interface implementation
+that indicates where the corresponding server or client code is located.
 
-DHCP
-----
+Example: DHCP
+-------------
 
 The DHCP agent includes a client API, neutron.agent.dhcp_agent.DhcpPluginAPI.
 The DHCP agent uses this class to call remote methods back in the Neutron