As we see, if a subject is renamed, the backend ought to be capable to help new and previous subject names till all of the callers migrate to the brand new subject identify (backward compatibility challenge).
There are a number of methods to take care of this limitation:
- By no means rename fields when FieldMask is used. That is the only resolution, nevertheless it’s not at all times attainable
- Require the backend to help all of the previous subject names. This solves the backward compatibility challenge however requires additional code on the backend to maintain observe of all historic subject names
- Deprecate previous and create a brand new subject as an alternative of renaming. In our instance, we’d create the
title_namesubject quantity 6. This feature has some benefits over the earlier one: it permits the producer to maintain utilizing generated descriptors as an alternative of customized converters; additionally, deprecating a subject makes it extra distinguished on the buyer facet
Whatever the resolution, it is very important do not forget that FieldMask makes subject names an integral a part of your API contract.
Utilizing FieldMask on the Producer (Server) Facet
On the producer (server) facet, pointless fields may be faraway from the response payload utilizing the FieldMaskUtil.merge() methodology (traces ##8 and 9):
If the server code additionally must know which fields are requested with a purpose to keep away from making exterior calls, database queries or costly computations, this info may be obtained from the FieldMask paths subject:
This code calls the
makeExpensiveCallToScheduleServicemethodology (line #21) provided that the
schedule subject is requested. Let’s discover this code pattern in additional element.
SCHEDULE_FIELD_NAME fixed accommodates the identify of the sphere. This code pattern makes use of message sort Descriptor and FieldDescriptor to lookup subject identify by subject quantity. The distinction between protobuf subject names and subject numbers is described within the Protobuf Area Names vs Area Numbers part above.
(2) FieldMaskUtil.normalize() returns FieldMask with alphabetically sorted and deduplicated subject paths (aka canonical kind).
(3) Expression (traces ##14 – 17) that yields the
scheduleFieldRequestedworth takes a stream of FieldMask paths, maps it to a stream of top-level fields, and returns
true if top-level fields comprise the worth of the
ProductionSchedule is retrieved provided that
If you find yourself utilizing FieldMask for various messages and fields, contemplate creating reusable utility helper strategies. For instance, a way that returns all top-level fields based mostly on FieldMask and FieldDescriptor, a way to return if a subject is current in a FieldMask, and many others.
Some entry patterns may be extra frequent than others. If a number of customers are all in favour of the identical subset of fields, API producers can ship consumer libraries with FieldMask pre-built for probably the most incessantly used subject mixtures.
Offering pre-built subject masks simplifies API utilization for the commonest eventualities and leaves customers the pliability to construct their very own subject masks for extra particular use-cases.
- Utilizing FieldMask can restrict your capability to rename message fields (described within the Protobuf Area Names vs Area Numbers part)
- Repeated fields are solely allowed within the final place of a path string. This implies you can not choose (masks) particular person sub-fields in a message inside an inventory. This may change within the foreseeable future, as a just lately permitted Google API Enchancment Proposal AIP-161 Area masks contains help for wildcards on repeated fields.
Protobuf FieldMask is an easy, but highly effective idea. It might assist make APIs extra strong and repair implementations extra environment friendly.
This weblog submit lined how and why it’s used at Netflix Studio Engineering for APIs that learn the info. Half 2 will make clear utilizing FieldMask for replace and take away operations.