gRPC Versioning and Folder structure

[Robert Hardisty]

Hi all,

Does anyone have an example of a good folder structure for maintaining different API versions for both the server and client? Lots of good examples on the proto files being versioned, but not much on server and almost non-existent on client. (preferably python, but doesn't really matter that much)

e.g.

• https://medium.com/stackpulse/grpc-in-practice-directory-structure-linting-and-more-d4d438ac4f86
• https://learn.microsoft.com/en-us/aspnet/core/grpc/versioning?view=aspnetcore-7.0#version-number-services

Best,

Bob

[Altay Sansal]

On top of what Robert provided, I want to add some more context here. It may help us get more targeted answers.

We have already defined multiple versions of protobufs based on the best practices. We have v2 and v1, and v2 is not backward compatible and we have some users of v1.

We have server and client libraries in Python that uses code generated by the proto compiler. We are trying to minimize the user-facing API changes. 

What would be the best way to structure our server/client code? Upon research we found the following patterns:

1. Define services with v1 and v2 suffixes and move business logic to common modules.

2. Add a version field to the protobuf definition and handle the selection at runtime using a router design pattern (to avoid if/else)

3. Make a v1, v2 submodule within our client and server libraries, however it will duplicate some code and add more hierarchy.

P.S. We basically want to maximize maintainability, minimize technical debt, and make it streamlined for the users of the client library.

Thanks a lot!