[Change request]: No write operation declares 409 Conflict as a possible response, though a unique-constraint conflict is a normal outcome

[bartvriesema]

Organization

Maastricht University

Project

No response

Contact Details

b.vriesema@maastrichtuniversity.nl

Short description

None of the spec's 26 POST/PUT/PATCH operations list 409 among their documented responses, even though a unique-constraint conflict is a completely ordinary outcome for several of them.

Most resources have at least one field meant to be unique per the domain (e.g. primaryCode scoped to its codeType, or similar natural keys). A client PUTting/POSTing a value that collides with an existing resource's
unique field is a normal, expected error case andnot a server malfunction. 409 Conflict is the standard HTTP status for exactly this situation.

Example: PUT /persons/{personId} with a primaryCode/primaryCodeType combination that already belongs to a different person. The only responses currently documented for this operation are:

200, 201, 202, 400, 401, 403, 404, 405, 406, 429, 500

A server has two reasonable options when this happens: return a generic 500 (misleading as it's not a server error), or return 409 (correct, but technically undocumented). This isn't specific to /persons as the same gap applies to essentially every write operation whose resource has a uniqueness constraint (course offering associations, programme offering associations, test component offerings, organisations, etc.).

Version

v6

Usecase

No response

Which institutions support this change?

No response

Proposed solution

Add 409 to the documented responses of write operations (POST/PUT/PATCH) on resources with a spec-implied unique field, with a description along the lines of "the request conflicts with an existing resource's unique identifying field(s)".

Requests and responses

All POST/PUT/PATCH requests are affected

What is your question for the OOAPI work group?

Can we add 409 Conflict to all the affected requests