REST: inconsistent use of PATCH and PUT

[yvespp]

We inconsistently use PATCH and PUT to update a resource. We use PATCH and PUT when only the value of a field can be sent. We use PATCH to send partial resources and only the value. Deployment API:

• PATCH /deployments/{id : \d+}/confirm: a partial deployment resource can be sent
• PATCH /deployments/{id : \d+}/date: only a int can be sent
• PUT /deployments/{id : \d+}/state: only a string can be sent
• PUT /deployments/{id : \d+}/updateState: only a string can be sent
• PUT /deployments/{id: \d+}/jobs/{nodeJobId: \d+}: only a string can be sent

The recommendation seems to be to use PUT if the whole resource is sent and PATCH when only some fields are sent. PUT should be idempotent. PATCH should define it's own media type (content-type):

• http://restful-api-design.readthedocs.io/en/latest/methods.html
• https://stackoverflow.com/questions/28459418/rest-api-put-vs-patch-with-real-life-examples

Commands should be POSTed to a subresource and a 303 pointing to the original resource should be returned (e.g. copyFrom resource):

• https://stackoverflow.com/questions/2443324/best-practice-for-partial-updates-in-a-restful-service

Sending only values doesn't seem to a commonly used pattern.

We should agree on when to use what and cleanup the rest api accordingly.