You should assume that any code you distribute will be around forever and
people will not update it. With this in mind, you should plan for
backwards compatibility forever and design your APIs appropriately. If you
have special knowledge that you can update all clients/ servers (via some
sort of auto updating package manager), then you need to at least support
all methods until you know for sure all have updated. You can include a
user agent string in the headers of your API calls to indicate what version
is running.
In general:
- As you said never reuse a field number
- Never change the type of a field. Even if you know what you are doing,
don't.
- If you are on proto2, never use required fields. They are more dangerous
than you think. They do not stand the test of time
- Don't use or depend on default values.
There are a couple ways of supporting older clients. One way is the union
style:
message DoSomethingRequest {
DoItWayOne first = 1;
DoItWayTwo second = 2;
}
When you want to add a third way, just add it in. Servers need to check
which way is set and use the appropriate code path. Also all servers will
need to be updated before releasing it in the clients.
Always make sure that each client can work with the current server version
and the next server version. Serves must work with the current client and
the next client. This forms a chain of compatibility that makes rolling
out new versions easy and *makes rolling back safe*!
Hopefully this helps.
On Monday, June 20, 2016 at 11:58:48 AM UTC-7, Scott Devoid wrote:
>
> Hi all,
>
> What are the 'best practices' for handling service changes and API
> versioning in gRPC? At the protobuf level, I know the answer is:
> append fields and never reuse a field number. Or at the very least,
> comment out the field and wait until you can be sure that no component
> uses the old field.
>
> But there are two scenarios that I can think of:
>
> - Adding RPC methods or altering RPC method signatures. I assume both
> the client and the server need to agree here? Do people implement a
> "GetVersion()" method? or something else?
>
> - When the client wants to send fields in a request that are
> semantically required but the server's version of the protobuf doesn't
> include those fields. Is there a way for the server to indicate that
> it received fields that it could not parse?
>
> Thank you!
> ~ Scott
>
--
You received this message because you are subscribed to the Google Groups
"grpc.io" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/grpc-io/6d1d344c-c04d-49c7-b840-65c5a9cd240f%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
