REST APIs documentation issues / questions


Various items in the documentation.

1. 'timestamp' is documented as the standard parameter name for times in the API. In the openEHR RM specs, we use 'time' or 'xxx_time' to mean this, and I don't think the terminology 'timestamp' is ever used.

2. Error code 409 is defined as
Conflict Indicates that the request could not be processed because it might generate a duplicate or a conflict

I think it would be clearer to have an error code that corresponds to creation of duplicates. What other kinds of conflicts are there? Note that creating a duplicate is also a pre-condition fail error condition.

3. In the documentation about date/time format, it probably should be made clear that TZ is only supplied when needed and that when not supplied, the local TZ is assumed. A secondary concern is that TZ probably should be added to all date/times committed to openEHR systems, to enable time information in EHRs shared across timezones to be computed properly.

4. In the abstract spec, I have documented pre-condition and post-conditions. Is there any way to show post-conditions in the REST API spec? Could it just point to the abstract spec, in order to show what should have occurred on the server? See e.g. 'Create EHR' => create_ehr() (

5. Typo in text for 409 error on 'Create EHR with id' call - 'already already'.

6. I created abstract definitions for create_ehr_for_subject() and create_ehr_for subject_with_id(); (see - do we not want these in the REST API - for many current systems, these will be the default form of the call I think. This seems specifically odd given that there are REST calls like 'Get EHR Summary by subject id'.

7. The call 'Get EHR summary by subject id' can result in >1 EHR Summary; is this handled properly?

8. In the abstract spec, I proposed calls for setting and unsetting is_queryable and is_modifiable - would these be useful in the REST API? (See

9. There is a call 'Get versioned EHR_STATUS version by time' which I think should be called 'Get EHR_STATUS version by time' - the result is a VERSION, not a VERSIONED_OBJECT. Any other similar calls should be checked as well.

10. After reading through various parts of the main definition, I think the parameter 'version_at_time' is confusingly named - it would be better to just name it 'time' or 'version_time'.




Thomas Beale




Affects versions