title: Versioning of REST webservices on top of gRPC
body: <p>I've implemented an API service using gRPC with protocol buffers and then used <a href="https://github.com/grpc-ecosystem/grpc-gateway" rel="nofollow noreferrer">grpc-gateway</a> to expose that as a set of REST webservices.</p>
  
  <p>Now I'm getting to the point where I'm having to maintain different versions of the API and I'm stuck.</p>
  
  <p>In my proto file I have a handler like this defined for instance</p>
  
  <pre><code>rpc MerchantGet (MerchantRequest) returns (MerchantResponse) {
      option (google.api.http) = {
          get: "/v1.1.0/myapi/merchant/{MerchantID}"
      };
  }
  </code></pre>
  
  <p>In my Go code of course I then have a function, <code>MerchantGet</code>, to which <code>GET</code> actions to <code>/v1.1.0/myapi/merchant/{MerchantID}</code> are mapped.</p>
  
  <p>Now, let's say I want to add more functionality to the <code>MerchantGet</code> method and release a new version. I intend to maintain backwards compatibility as per the <a href="https://semver.org/" rel="nofollow noreferrer">Semantic Versioning Specification</a> so if I understand correctly that means I can make underlying changes to my <code>MerchantGet</code> method and have it supersede the older method as long as it does not require different inputs from the 3rd party (<code>MerchantRequest</code>) or change the response sent to the 3rd party (<code>MerchantResponse</code>) other than by adding additional fields to the end of the response. (Correct me if I'm wrong in this assumption).</p>
  
  <p>My question is, how do I write proto handlers to serve a method to endpoints of different versions? One option that came to mind would look something as follows:</p>
  
  <pre><code>rpc MerchantGet (MerchantRequest) returns (MerchantResponse) {
      option (google.api.http) = {
          get: "/v1.6.0/myapi/merchant/{MerchantID}"
          additional_bindings {
              get: "/v1.5.0/myapi/merchant/{MerchantID}"
          }
          additional_bindings {
              get: "/v1.4.2/myapi/merchant/{MerchantID}"
          }
          additional_bindings {
              get: "/v1.4.1/myapi/merchant/{MerchantID}"
          }
          additional_bindings {
              get: "/v1.4.0/myapi/merchant/{MerchantID}"
          }
          additional_bindings {
              get: "/v1.3.0/myapi/merchant/{MerchantID}"
          }
          additional_bindings {
              get: "/v1.2.0/myapi/merchant/{MerchantID}"
          }
          additional_bindings {
              get: "/v1.1.0/myapi/merchant/{MerchantID}"
          }
      };
  }
  </code></pre>
  
  <p>But surely this can't be the idiomatic way of achieving this? It's certainly not very elegant at all as, with each new minor version or patch, I would have to extend these <code>additional_bindings</code> to each of my methods (above I'm just using one method as an example).</p>