search

aip-dev / google.aip.dev

API Improvement Proposals. https://aip.dev/
Other
1.08k stars 491 forks source link

What to do when you do not support partial update #70

Open lukesneeringer opened 5 years ago

lukesneeringer commented 5 years ago

From @jgeewax:

A few APIs either can't or won't support partial update for a variety of reasons:

  • For security reasons, they cannot have the situation where a customer updates something and has leftover values that they weren't aware of on the client side.
  • They need the ability to update inside maps and go/advanced-field-masks isn't implemented yet.
  • They have some other technical limitation that only allows them to update the entire resource.

What do you do? Currently we've seen several options:

  1. Use Update that relies on the PUT verb.
  2. Use Update with PATCH and a FieldMask update_mask that is simply ignored.
  3. Use Update with PATCH and omit a FieldMask update_mask
  4. Use Update with PATCH and a FieldMask update_mask that fails with a bad request if the value is set to anything other than null, '', or '*'.
  5. Use Replace that relies on the PUT verb

My stance is that we should go with option 4 generally, and in rare exceptions (such as the security requirement in the examples above), go with option 5.

lukesneeringer commented 5 years ago

For what it is worth, my instinct is that option 5 is better than option 4. I am nervous that option 4 obscures the departure from the norm.