The idea is to add HEAD method, similar to GET, to check whether a resource exists, but without returning any content in the body, just http status 200 or 404.
Although I understand the need from SM perspective, described in openEHR Platform Service Model, I wonder what is the real value in REST APIs. If HEAD returns only 200/404, there is only a network/traffic optimization, but clients would still have to make 2 requests (HEAD+GET) to get a single resource, and the server would still have to consult 2 times internal persistence layer. I can imagine another approach is to just treat GET 404 errors gracefully.
If on the other hand the HEAD would return also version-id headers besides 200 status, then I can see a use-case where clients may “check” for version_uid updates, so that in case of an update they populate the right preceding_version_uid in the If-Match header.
Does implementers have real use-cases or any opinion on this aspect?
I read the issue and your comment a week ago, but dismissed my thoughts for the moment, sorry
From my actual work I don’t see a use-case for this. “Just” making testing more efficient and easy (as in direct) wouldn’t justify a change of API, from my perspective.
Just off the top of my head I can imagine it also make sense in scenarios where you want to check for validity of cached components in the UI. Yet existing tool are already doing that in some form or another, but I don’t know if via AQL, a native solution or something else.
Regarding your version-ID header idea: From a technical perspective only, I think that makes a lot of sense.
You were talking about this operation and the following behavior, right? EHR API
A request like GET {baseUrl}/v1/ehr/7d44b88c-4199-4bad-97dc-d78268e01398/versioned_composition/8849182c-82ad-4088-a07f-48ead4180515/version?version_at_time=2015-01-20T19:30:22.765+01:00 could be executed as HEAD (with and without the parameters, just like the GET) and returns useful headers:
For the Conformance Framework implementation in EHRBASE we used just the GET for all the has_*** operations of the SM. Though it is not a direct mapping from SM to REST, the GET is both has_xxx and get_xxx.
has_xxx() works when the client wants to do a check of existence, no client will send two requests, if they need the EHR, COMPOSITION, DIRECTORY, etc. they will issue a GET request not a HEAD+GET.
For me it adds value to REST and flexibility in terms of giving clients more options to work with the REST API, for some that network traffic improvement might be a good feature, while others might not invoke the HEAD at all.
In terms of conformance, I think it is more clear to have 1-to-1 mappings of operations, though we can say those HEAD requests in the REST API are optional to implement since could be implemented with the GET, so companies could also choose implementing them or not (and still be compliant).
