as I am currently implementing the semantics of the EHR_STATUS.is_modifiable flag, i was wondering which status code shall be returned if a request (i.e. POST /v1/ehr//composition) is denied because of EHR_STATUS.is_modifiable=false.
Should it be a simple 400 and the client can figure out what went wrong from the message or should it be more specific?
I was thinking 403 could make sense, because in essence a failed is_modifiable check is a forbidden operation which the server understood, but is refusing to fulfil.
I would love to get some input/opinions on this. A hint that I missed the correct status code in a part of the specification is also welcome of course.
Thanks,
Vinzenz
EDIT: Some input on the error message returned would also be appreciated, so that this does not differ too much from one openEHR server to the next.
As far as I know, and I did a search in the REST API spec just to confirm, we are not considering the flags in the REST API spec, which we should.
For instance, in the HTTP status section we should have some mention and EHR changes when is_modifiable is false. Extending that for queries when is_queryable is false.
There should be a mention to the result when is_modifiable == false on:
POST /composition
PUT /composition
DELETE / composition
POST /contribution
POST /directory
PUT /directory
DELETE /directory
PUT /ehr_status
(which are, I think, all operations that modify an EHR in the current REST API spec)
For the response status under that case, I wouldn’t consider 403 since this is not an access rights issue, and I would consider 400 to be an actual error with the request, which this case is not, it’s something about the state of the server that doesn’t allow the operation to be executed. So I would consider:
405 method not allowed (I’m not sure if this should be a persistent response for the API endpoint or could vary for different EHRs)
406 not acceptable
409 conflict
In any case, this should be defined by the SEC since it’s not yet specified, so your implementation could for now have a patch for this using any code but wouldn’t be officially conformant with the spec until this is formally defined.
When this is specified, all servers should conform with it, so there won’t be much variation then, a server will “conform or not” with the specs.
I would put this in the next SEC meeting agenda @thomas.beale
@pablo Thanks for the quick response.
I think for now i will go with 409 because it seems to be the best fitting match when going off the usual status code definitions.
406 is intended for HTTP content-negotiation which is a different thing.
405 for individual EHRs sounds valid HTTP wise, but feels a little off to be honest, since from a developers perspective it usually indicates that you chose the wrong HTTP method for the endpoint and not that the server is actually preventing you from accessing an endpoint that in it self is valid for that HTTP method.
I’m looking forward to it being included in the REST-API spec, so we can be officially conformant
We don’t allow any contributions (apart from changing EHR_STATUS) to non-modifiable EHRs. We find Bad Request (400) response quite okay for such a situation. We return it for our proprietary REST interface, but I’m not sure at the moment what we do with the openEHR REST; perhaps we (wrongly) fall-back to 500 because 400 is not specified for such cases. We look forward for it to be.
As for non-queryable EHRs, we reject AQLs (with 400 again) that specifically ask for non-queryable EHRs (by EHR ID in predicate within CONTAINS EHR, or within the WHERE part). I’m not sure this is very useful, and I’m not sure where we got this idea, but it might be worth it if someone would check the specification in case it says anything to this point.
@matijap Regarding the is_queryable limitations (which will be coming up for me to implement as well):
EHR Information Model states that is_queryable determines if an EHR is included in population queries, meaning with is_queryable=false it would still be queryable by explicitly selecting it in the FROM clause (FROM EHR [ehr_id/value=<some-id>]), but i will create a separate topic for that since i am also not quite sure if the definition of population query i gathered from the spec is the complete picture. Topic for is_queryable: Which queries should EHR_STATUS.is_queryable actually affect?
I am starting to think we should make EHR_STATUS completely invisible to AQL querying for all EHRs, and visible only via dedicated API calls - which would mean creating a few new ones. It really is meta-data in the original sense of the word, and I think we should probably treat it like that.
