Description

The current REST responses do not enforce any complelty minimal responses so that 204 No content is returned that in my experience confuses developers.

In many case too there is some minimal valuable content e.g. the ehr_id or composition_uid which is oftne used for the next stage of processing. THis is currently returned in the ETag header but this is often obscure instead REST libraries and requires the quote marks to be stripped.

Suggested v. minimal responses...

/composition

POST - the new uid
PUT - the updated uid
DELETE - the deleted uid

/ehr
POST - the new ehr_id
PUT - the ehr_id

/definition/template
POST - the new templateId, uid and dateCommited
PUT - the updated templateId, uid and dateCommited
DELETE - the deleted templateId, uid and dateDeleted

/query - an empty Resultset array?

I'm aware that might be at odds with 'proper' Restful design but the current 204s are quite confusing.

blocks

Activity

Show:

Ian McNicoll August 28, 2024 at 3:26 PM

Ian McNicoll August 5, 2024 at 12:23 PM

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.

Pablo Pazos June 3, 2024 at 1:53 PM

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.

John Meredith June 3, 2024 at 11:23 AM
Edited

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.

Ian McNicoll June 7, 2021 at 5:14 PM

I can’t argue ‘technically’ but I still think this is a big mistake - it is just another barrier that causes confusion and could be easily be softened but I am just a hacker however …

Pinned fields
Click on the next to a field label to start pinning.
Details

Reporter

Ian McNicoll

Raised By

Ian McNicoll

Components

Affects versions

Created September 21, 2020 at 1:43 PM
Updated August 28, 2024 at 3:26 PM