Practical API Design in Netflix, Part 1: Using Protobuf FieldMask By Netflix Technology Blog September, 2021

As we see, if a field name is changed, the backend should be able to support new and old field names until all callers are moved to the new field name (backward compatibility issue).

There are several ways to address this limitation:

  • Never change the field name when using FieldMask. This is the simplest solution, but it is not always possible
  • Backends are required to support all old field names. This fixes backward compatibility issues but requires additional code in the backend to keep track of all historical field names
  • Delete the old one and create a new field instead of changing the name. In our example, we will create title_name Field No. 6. This option has some advantages over the previous one: it allows the producer to use the generated descriptor instead of the custom converter; Also, underestimating a field makes it more prominent to consumers

Whatever the solution, it’s important to remember that FieldMask makes field names an integral part of your API agreement.

Using the fieldmask on the producer (server) side

Unnecessary fields can be removed from the feedback playload using the FieldMaskUtil.merge () method (lines ## 8 and 9), next to the producer (server):

If you need to know which areas of the server code are requested to avoid external calls, database queries, or costly calculations, this information can be found in the Fieldmask Path field:

This code calls makeExpensiveCallToScheduleServiceMethod (line # 21) only if schedule Fields are requested. Let’s explore this code sample in more detail.

(1) SCHEDULE_FIELD_NAME The constant contains the field name. This code uses message type descriptors and FieldDescriptor to find field names by sample field numbers. The difference between protobf field name and field number is described in the Protobf field name vs. field number section above.

(2) FieldMaskUtil.

(3) The expression (line ## 14 – 17) that yields scheduleFieldRequestedThe standard fieldmask takes a stream of paths, maps it to a stream of top level fields, and returns true If the top level fields have values SCHEDULE_FIELD_NAME Constant

(4) ProductionSchedule Only if rescued scheduleFieldRequested Is true.

If you end up using FieldMask for different messages and fields, consider creating a reusable utility helper method. For example, a method that returns all top-level fields based on FieldMask and FieldDescriptor, a return method if a field is present in FieldMask, and so on.

Some access patterns may be more common than others. If multiple consumers are interested in subsets of the same field, API developers can pre-build client libraries for the most used field combinations.

Providing pre-built field masks simplifies API use in the most common situations and leaves consumers the flexibility to create their own field masks for more specific uses.

  • May limit the ability to rename message fields using FieldMask (described in the ProtoBoff Field Name vs. Field Number section)
  • Repeat fields are only allowed in one path string end position. This means that you cannot select individual sub-fields in a message within a list (mask). This may change in the future as the recently approved Google API Improvement Proposal AIP-161 field mask includes support for wildcards in repeated fields.

Protobuf FieldMask is a simple, but powerful concept. This can help APIs become more powerful and service implementation more efficient.

How and why this blog post is used for APIs in Netflix Studio Engineering that read data. Part 2 will cover the use of fieldmasks for updating and removing operations.

Source link

Related Articles

Leave a Reply

Your email address will not be published.

Back to top button