The main concern I have with allow_missing is duplication. Does it overlap with some existing api, such as the new apply method?

I could imagine there’s some differences:

  • If a field is missing, an apply could reject the request, while update with allow_missing would silently accept it with some default.

Today, apply with fields missing does not actually state that the request should be rejected. Instead, it states:

Note that PUT requests with fields missing in the resource may result in overwriting values in the resource with existing values. For that reason, AEP-compliant APIs generally use the PATCH HTTP verb.

So the behavior is actually one of:

  • use the default values for those fields.
  • do not modify the existing one.

But does not clarify which is expected. This should be fixed regardless.

If the choice is to leave unset values unmodified, that it is identical to the behavior of update with allow_missing.

If default values are chosen, then in proto, that would be nearly identical to an update with a full field mask set (a wildcard *).

But thinking a bit about that second user journey, generally the idea that one would like to reset a resource back to it’s default values is somewhat non-sensical:

  • If one would like to update a resource back to it’s default, set it explicitly in your update.
  • If you would like to leave the value alone, leave it unset.

This is a relatively easy thing to accomplish in OAS: one can examine the fields in a resource, see if they are unset, and then in turn only modify the ones that are set.

For protobuf, this is a bit more difficult because of the fact that non-optional fields are set to their default values. However, even there I think there’s a solution: effectively make every protobuf field explicitly optional, at which point it behaves just like json.

In the above case, one can just set the fields they would like to modify, or are aware of. Combined with a field mask, this would determine wet

User journeys #

What you’re trying to do with a field how to accomplish it in protobuf how to do it in REST
Set a field to empty include it in the field mask, set field as null set value as none
Don’t modify a field don’t include the field in the field mask, set field as null don’t include value in json payload
Set a field to a specific value include the field in the field mask, set field with desired value include value in json payload

Conclusions #

Ultimately, allow_missing and update, due to it’s inclusion of field masks, are a more flexible version of the apply method. Generally clients should just use that method across the board.

In addition, the following guidance should probably be added:

  • update protobuf guidance that all fields should be optional.
  • the apply field should clarify whether it will use default values if a field is missing, or leave the field unmodified.
  • the apply field should clarify that a request with required fields missing will reject the response.