3 ms·
I use grpc-web and protocol buffers. Renaming fields doesn't matter -- if the client and server disagree about the name of a key, it doesn't matter, because th
by jrockway 7y ago
I use grpc-web and protocol buffers.
Renaming fields doesn't matter -- if the client and server disagree about the name of a key, it doesn't matter, because the transport layer uses the tag number, not the name. (Compare this to JSON, where changing the name does break clients.)
Adding fields also doesn't matter, but this is where it starts to get tricky. If a client sends a request without a field that the server expects (i.e., an old version of the client), the message will parse OK, but the server could still say "hey actually that's required, buh bye". If you do this, you lose the backwards compatibility. So don't do that.
Removing fields is something you can basically never do if you want compatibility. You can rename them to deprecated_whatever, though, and see what code still uses them by the fact that they no longer compile. (Binaries using that field can still exist and will continue to work, of course. But at least you can have a transition period where people writing new code will think "hmm, this is probably going away" and won't depend on that field.)
(There are also some additional mechanical details that the protocol buffer documentation talks about. Maybe an int32 isn't big enough so you want an int64. Old clients can still talk to a server that has changed the type of an int32 field to an int64, but eventually it's going to lose data because it didn't allocate enough storage to manipulate an actual 64-bit value. But it does give you time when you think "a year from now this will be bigger than 2^32". You can change the definition today and eventually update all the clients.)
I think with care and the occasional update of a client, though, you can pretty easily keep things compatible forever. This is wayyyyy easier with SPAs than any other sort of API consumer, because you have control over updating the client.
Often you are adding new features, which is the easiest case. You add a new field or RPC, and just start using it.
You can usually structure a change in semantics as a new feature, which makes the cases for which protobuffers excel even more common in practice. For example, say you have clients that depend on the ordering of results from a Lookup() call. You think that that sort is unnecessary and slow, and you want to change the semantics without breaking clients that depend on the ordering. You can just add a new RPC, FastLookup(), and start using that. Clients that use the new RPC will be faster, but old clients will continue to work using the old method. You can update all those (check your monitoring, you probably have a grpc_server_handled_total metric for every method), and after everything's updated, you can safely remove the code that implements Lookup() (either delete it entirely, or to really do it right, return codes.Unimplemented).
I think if you aim for incremental progress, it's pretty easy to achieve with the right tools. It's harder, but possible, even for public APIs where you can't update the client. But where you can update the client and all you have to worry about is browser cache? Easiest possible case ;)
- H8crilA 7y agoIndeed, this over 30 years old problem is easily fixable by following guidelines on protocol buffers. Or any other similar technology of this sort, like ASN.1 if you like antics. Protos are just quite popular and therefore a safe commodity bet.
- tdhoot 7y agoYou can also remove a field by reserving the tag number and optionally the name. New binaries will fail to compile but previously persisted values can still be read back by old binaries. Also ensures no one uses the same tag number later and reads bad data.