optimistic locking with ETags

[pvdbosch]

In GitLab by @pvdbosch on Nov 14, 2019, 12:11

When creating or updating resources it may be necessary to expose conflicts and to prevent the 'lost update' or 'initially created' problem. Following RFC 9110 section "HTTP: Conditional Requests" this can be best accomplished by supporting the ETag header together with the If-Match or If-None-Match conditional header.

See https://opensource.zalando.com/restful-api-guidelines/#182

Optimistic locking for update/create scenarios with If(-None)-Match headers and status code 412 isn't well documented currently in our guidelines. Instead 409 is listed for updates with a failed optimistic locking, but this is in conflict with the RFC.
Only the use of these HTTP headers for caching purposes with GET is currently documented.

When we agree to use 412, we could introduce a specific problem type for failure by optimistic locking (412 Precondition failed might be used in other circumstances and be too vague).

Another section talks about some corner cases (e.g. when using embedding), though I that might be a bit overkill for the styleguide:
https://opensource.zalando.com/restful-api-guidelines/#optimistic-locking

[pvdbosch]

we can also document 428 - Precondition required https://httpstatus.in/428/ if If-Match header is missing, but this may be more difficult to implement : if OpenAPI document mandates the header, it's difficult the return an different error than for other cases of an invalid request.