Deprecate all PUT operations
Proposal: Deprecate all PUT operations (advertise will be removed whenever we release a V3) and, going forward, use only POST and PATCH for new write operations.
Justification:
- In the majority, possibly all, cases our data model is such that resources can only be created with a POST operation and only a limited set of properties can be changed after a resource is created, which is clearer to understand with a PATCH operation. Accordingly the use of PUT is redundant.
- Since we (almost) never allow a resource, in its entirety, to be 'replaced' we (almost) never honour the spirit of a PUT operation anyway.
- The existence of redundant operations adds confusion for API consumers in working out how to consume the API.
- The existence of redundant operations adds complexity for implementors as we have to implement two sets of validation rules for every update operation.
- PUT operations are required to be idempotent which is an undesirable constraint for operations that may trigger network provisioning.
Edited by Mustafa Arif