notes from a REST API meeting 2024:

• try with prefer=identifiers

• 2024-08-28: consider aligning with FHIR specs on the flow, consider (minimal, representation, identifier); minimal remains as 204 not-content, identifier is status 200/201 as very simple object with identifier; or text/plain (via Accept) with only id

• consider the case of error-representation and OperationOutcome

I found this FHIR Chat discussion which crosses into today;s discussion https://chat.fhir.org/#narrow/stream/179166-implementers/topic/OperationOutcome.20code.2Fdetails.20for.20specific.20use.20cases/near/450280310

I’m coming back to this, as it continues to raise questions/confusion from new openEHR developers. We are making this harder than it should be for newbies.

I’m happy to accept that 204 no-content responses are perfectly reasonable and I think Pablo is on the right track in saying that the issue is that we have no definition of ‘minimal’, which allows no-content and therefore may generate a 204.

So either we try to agree that ‘minimal' should be standardised and return some sort of actual response, at the very least a status message, or if people want to allow for a non-content response/ local variation, then we add a new 'standard’ response type, which does return a standard, agreed response and is the default.

Anything we can do to lower the barrier of entry, IMO.

@John Meredith the spec says this depends on what the client (developer) sends in the request, in the Prefer header. If they send Prefer: return=minimal then it’s up to the server to return a minimal representation or no content. If it’s a POST, the minimal representation will return 201 Created, the no content will return 204 No Content, which are both HTTP standard response codes. To work with this developers should know the openEHR REST API spec and the HTTP spec for the response codes. If someone is confused by that, it might be that they are not familiar with either of those. IMO the 201 vs 204 is very clear and I don’t think is a real issue. The only argument I have is about the minimal representation which I think is not 100% standard, though we show samples in the REST API spec. It would be nice to standardize what we expect for the minimal representation.

Apologies for adding to an old issue but this is causing very real confusion to our development teams where there is the expectation for a 201 and details on the resulting composition that has been created. I’d appreciate this being looked at although returning a more detailed ack message in the 204 would equally be useful.