REST API: missing 204 responses?

[pablo (Pablo Pazos)]

Hi SEC, there is something I need to double check, we might be missing some responses in the POST/PUT endpoints.

From: APIs Overview openEHR specs

A Location header indicating the direct URL to access the resource MUST be part of the service response. If there is no payload content to be returned, the service SHOULD use HTTP status code 204 No Content.

Then in EHR API openEHR specs

There is no 204 response.

I don’t know if a 204 was not included because it’s clearly specified in the APIs Overview section, or if we just missed that response.

IMHO, for reading clearness I would prefer to add all the possible responses on each endpoint, instead of having some external default, because readers would need to check on different places of the spec when implementing or using one endpoint.

What do you think?

PS: the same happens with PUT /ehr, though I see in PUT /ehr_status that the 204 is there. But again in POST/PUT /composition there is no 204. For POST /ehr/id/directory there is no 204, for PUT there is. So for consistency it would be better to add it on all or to remove it from all.

[ian.mcnicoll]

@pablo

IMHO, for reading clearness I would prefer to add all the possible responses on each endpoint, instead of having some external default, because readers would need to check on different places of the spec when implementing or using one endpoint.

I agree with this. I know that a lot of people ‘miss’ the otherwise very clear guidance on Headers as it is on a different page.

At the very least we should make the pointer to that information clearer but better still, as Pablo suggests, replicate it each time, even though this is redundant