Search code examples
thriftapi-versioning

Best practice to retire an defined Thrift API?

Just curious about what will happen in the below scenario?

  1. An defined API is removed in the latest thrift service definition;
  2. The implementation on server end upgrades to latest definition (i.e., doesn’t have implementation about the removed API any more);
  3. Some of clients may still stay on the outdated service definition and have traffic to the deleted API.

As a more general question, is there any best practical to retire an existing API (i.e., once defined in the .thrift file)?

Solution

  • That's one of the benefits of soft-versioning, which is not a Thrift-only feature. The API may change over time, and as long as a certain, very minimal, set of rules is honored, there is a well-defined way in which applications will behave.

    With regard to Thrift these rules include that one should never change the type of a particular field ID of any given struct member or argument. Same is true for service names and method names. The numeric field/argument IDs and the service/method names are the identifiers used in the data on the wire.

    Hence,

    • if the type of a field/argument changes, the numeric ID should also be changed
    • fields and methods that have been deprecated should be commented, not removed from the IDL (to prevent them from being reused later)

    The last point worth mentioning is about the usage of required: This attribute may not be removed from a published API struct member, because of the way of how the required semantics work.

    Otherwise you will run into compat issues when old clients are calling new services, or vice versa.