Request

GET ./ehr/{ehr_id}/composition?start_time=ge20170218T0000Z&archetype_id=openEHR-EHR-COMPOSITION.report.v1&template_id=pathology_report

Response

Good question. Following the RM it would be SET<OBJECT_REF>. This wouldn't be very useful for an application so we need a Resultset structure of the matching compositions or a minimal composition data structure.
My preference would be a Resultset structure that aligns with an AQL query results with a server defaulted set of composition attributes. An additional request parameter of comma separated composition attributes could be provided to override these default attributes. For example:
&selectedAttributes=uid,name,start_time,health_care_facility-name

EDIT: There is a wikipage diskussing this issue too https://openehr.atlassian.net/wiki/spaces/spec/pages/94005928/Filtering+for+Simple+Queries+in+REST+APIs

We are focusing now (initial phase) mainly on /ehr, /template and /query but we will have to support eventually also Demographics.
Any idea or preferences before building something in apiary?

The error conditions 400 and 409 defined on upload template should presumably also exist on upload archetype.

The body contents returned in response to this call contain a contribution field whose type should be OBJECT_REF but the contents in the example do not match an OBJECT_REF instance.

PUT for Composition has :

• Request with full representation
• Request no content

They are identical in the example. Is this a typo? Should the Request no content have an empty body?

I see an error that repeats by following the steps on the README for building the on the development folder.

Generating HTML file...
redocly build-docs [api]

Produce API documentation as an HTML file

Positionals:
  api                                                                   [string]

Options:
      --version            Show version number.                        [boolean]
      --help               Show help.                                  [boolean]
  -o, --output             Output destination file.
                                         [string] [default: "redoc-static.html"]
      --title              Page title.                                  [string]
      --disableGoogleFont  Disable Google fonts.      [boolean] [default: false]
  -t, --template           Path to handlebars page template, see
                           https://git.io/vh8fP for the example.        [string]
      --templateOptions    Additional options to pass to the template. Use dot
                           notation, e.g. templateOptions.metaDescription
      --theme              Redoc theme.openapi configuration. Use dot notation,
                           e.g. theme.openapi.nativeScrollbars
      --config             Path to the config file.                     [string]

Unknown argument: cdn

Current:

The existing versionUidofEHR_STATUSresource must be specified in theMatch-If header.
Ref https://github.com/openEHR/specifications-ITS/blob/master/apiary.apib#L436

+ Response 412
    `412 Conflict` is return when `Match-If` header doesn't match the latest trunk version. 
    Returns latest trunk version in the `Content-Location` and `ETag` headers.

https://github.com/openEHR/specifications-ITS/blob/master/apiary.apib#L548-L551

Does 2. implies that versionUid described in 1. should be the current trunk version? Or can versionUid be the UID of any version of the EHR_STATUS?

If it can be only the trunk version, is the versionUid needed? I think knowing the ehrUid and that the status is the trunk, that identifies just one version of the status.

Background:

See discussion at https://openehr.atlassian.net/wiki/display/spec/openEHR+REST+APIs

It can be hard for some implementers to support all kinds of calls, we could provide a well specified conformance ladder with basic levels that are easy to add but still are very useful for integrations. Defining R1+W1+Q1 should probably be first priority timewise.

Implementation levels (an initial suggestion)

• R1 Basic read-only. COMPOSITION+FOLDER listing and retrieval.
• R2 Level 2 read-only. R1 as above plus: Support for listing and retrieval of CONTRIBUTIONS, EHR_STATUS and EHR_ACCESS...
• W1 Basic write. Writing/updating COMPOSITIONS one by one. Creating new EHRs...
• W2 Level 2 write. W1 as above plus Writing several changes at once using a CONTRIBUTION...
• W3 Level 3 write. W2 as above plus multi-EHR-spanning-commit mechanism (allowing Atomic correction moves etc between different EHRs)
• QL1 Basic Query...
• QL2 Level 2 Query. Named/identified queries with dynamic parameters (allows stored procedures and other optimizations).
• CDS1...? Clinical Decision Support?

One system could for example support R1+QL1 another might support R2+W2

Suggested next steps

1. Discuss suitable levels
2. add short text about levels in Apiary intro text (and refer/link to related spec-document for more reasoning about levels)
3. add a level marker, e.g. "(Api Level R1)" to the description text of suitable resources/calls

I (@ErikSundvall) can make some initial changes to the file to illustrate and get started, then initiate a pull request.

I think we removed all the references to object_id and added explicit versioned_object_uid and version_uid for all the endpoints.

Quick search gives some uses of object_id in query and other files that might be incorrect or outdated:
https://github.com/openEHR/specifications-ITS/search?p=1&q=object_id&type=&utf8=%E2%9C%93

Please double check if we still use/need object_id.

Please see:
documentation for PUT here

I'd say an array of query parameters would be more appropriate instead of a query_parameter field

The value of query parameter is also wrong I think, at least it does not make sense since it does not refer to an actual parameter in the query such as ehr_id
and finally, the parameter syntax in that query should be $ehr_id according to aql spec and not :ehr_id

The post operation to upload a new opt to the server has an optional version parameter.

In the context of adl 1.4 based implementations, this parameter causes a number of issues.

• First of all, there is no mechanism in the RM to point at a specific template's version. archetype_details of Locatable (I think) allows us to point at a template via
  <template_id><value>BloodPressure</value></template_id>

but that is it. In Ocean's implementation, whatever the opt with that template id is, it will be used for validation. I suspect it may be the same for other vendors for adl 1.4 implementations and deployments.

• Since there is no mechanism to express preference for a particular version of an opt, there is no need for an opt upload to set the version. I could upload nine versions of a template but I have no way of associating a particular composition with a specific version of these templates.

• @wolandscat correctly pointed out that if templates are versioned then these versions should be assigned by the modelling tools and should be included in the template artefact itself.

Based on the arguments above, I cannot see any benefit for the version parameter here. I'd like to hear the original motivation/thinking for introducing this parameter.

It's not clear to me what the reverse domain name qualifier in the qualified query name pertains to. Whose domain is it? It would seem simpler to either have a flat id space, or else some kind of ids based on a pathing concept that allows queries to be classified in a tree-space.

This endpoint is defined as returning as VERSION but the body contents in the specification belong to an ORIGINAL_VERSION instance. Please state if inheritance for returned type should be supported and clients should consider that ORIGINAL_VERSION can be returned in this case.

The POST request for creating a new EHR is documented to return a data structure that consists of objects and string fields. However, it is not clear what these objects should look like in terms of RM types.

Please specify expected structures in regards to RM.

It should revert to the version just before deletion.

Updating resources COMPOSITION and DIRECTORY are somewhat similar methods (in scope of this question), but providing {preceding_version_uid} is handled differently in each case.

• PUT /ehr/{ehr_id}/composition/{preceding_version_uid} contains the uid as path parameter
• PUT /ehr/{ehr_id}/directory contains the uid as If-Match header parameter, which is said to be mandatory

Same is true for deletion too.

Why do these cases need different implementations of providing {preceding_version_uid}?

Following #73 the documentation wasn't updated to reflect the changes. See:

On #3 we mention ideas for how to approach the formats for the resources.

There is an idea of defining all the resources in XML + XSD, then transform the XMLs to JSON.

@bostjanl mentioned that some transformations might lead to very ugly JSONs.

Just to kickstart this conversaton, I have some experience with XML => JSON from the EHRServer, and the results are very impressive. In fact we transform what I think is the most complex structure in openEHR (a full composition) and the resulting JSON is really nice.

In our case we use staxon: https://github.com/beckchr/staxon/wiki/Getting-Started

I'll add some examples of the XML vs. the transformed JSON to see if this or something similar can work for us as a canonical transformation.

The other nice thing about the staxon output is that it can be transformed back into the XML.

There are more comments on @type: DV_INTERVAL vs @type: DV_INTERVAL < DV_QUANTITY > here: https://openehr.atlassian.net/wiki/display/spec/AQL+Result+Set+work+area.
Should we drop this extra information and only specify: @type: DV_INTERVAL?

At various locations, the rest specification states that create calls with representation set to minimal should return only headers, and one of those headers is Content-Type.
this is a grey zone: the relevant RFC (https://tools.ietf.org/html/rfc7231#section-3.1.1.5) says that a sender that sends a payload body SHOULD set the content type but it does not say that in case of no content this header should be set
Moreover, the technology stack we're using is opinionated and does not let setting the content-type header when the content is empty.
Unless there is an argument against it, could we please consider not making content-type header mandatory when there is no content?
I realise the limitation of a tech stack is not grounds for requests for change, but in this case what the spec is asking is not making a lot of sense to me

So please consider that as the source of my request
here is an example: https://www.openehr.org/releases/ITS/latest/docs/ehr.html#composition-composition-post

I think the structure of this repo should follow the target ITS formalisms, not the abstract components (RM, AM etc). So far I think we have:

• XSD
• BMM
• WSDL
• REST

At the moment, Antlr is considered a specification level formalism, although it is a directly usable technology as well.

Looking at https://rawgit.com/openEHR/specifications-ITS/master/docs/ehr.html#composition-composition-put

Under the Requests "with full representation", the Prefer header has both values representation|minimal (https://github.com/openEHR/specifications-ITS/blob/master/REST_API/includes/composition.apib#L86)

Since we are saying the response has the full representation, shouldn't the Prefer header be just "return=representation", giving both options there might be confusing.

Also we don't need to include both since are documented under the REPRESENTATION DETAILS NEGOTIATION section.

There are several non standardized implementations of "flat" openEHR RM JSON formats, that usually consist of lists of key-value pairs where the key is some kind of path. There are use-cases behind the creation of such formats and it would be good to provide a public specification of such a format.

Two of the flat formats are described at: https://github.com/ethercis/ethercis/blob/master/doc/flat%20json.md

(Please edit this issue ticket to add links to other flat-format descriptions if you know of any)
Background motivation of the need of tracking these thoughts as an official issue: ethercis/ethercis#74 (comment)

The latest version of spec uses the following wording under Authorisation and Authentication section:

Services SHOULD implement and support a HTTP Authentication and Authorization framework. See RFC 7235 or Mozilla’s HTTP Authentication for more details on this subject.

This makes me think I should implement basic auth. Discussions in the slack channel imply that this is not necessarily the case. Furthermore the spec makes the following statement:

Furthermore there is no assumption or recommendation being made in this specification about which authentication scheme should be used by services and clients.

which conflicts with the first excerpt above. Mentioning the implementation of an auth scheme with SHOULD , followed by a link regarding its details makes me think this should (notice the regular should here...) be implemented. If the spec is making no assumption, then why give the link to a specific auth scheme?

Please either clarify when/how it should be implemented or remove the part about http authentication, or at least the links to Basic Authentication (which is a specific scheme)

There are several issues to discuss regarding how to specify the Query resource. Including but not limited to:

1. Format of result set (see https://openehr.atlassian.net/wiki/display/spec/AQL+Result+Set+work+area )
2. Support for other Query formalisms than AQL?
3. Storing and executing stored queries (see previous discussion at https://openehr.atlassian.net/wiki/display/spec/openEHR+REST+APIs )
4. Long queries do not fit within the length limit of GET-requests, so there must be a way to POST queries too.
5. ...

Since openEHR spec does not describe the semantics of a deleted EHR and it is not currently clear how this could be expressed in the REST api, the reference to deleted ehr in the following text would better be removed:

404 Not Found returned when EHR with ehr_id does not exist or has been deleted or a version of an EHR_STATUS resource does not exist at the specified version_at_time.

This is necessary since this statement refers to functionality that is not defined in the current rest specs and therefore cannot be used to write tests for the get ehr status semantics above.

Did anyone defined an XSD for EHR, EHR_STATUS and FOLDER?

I think we need at least those for v0.1.

A related question: what do you think about the inclusion of EHR_ACCESS as a structure that will be used in the API?

IMO I don't think we should include it if no one uses it to model access constraints to the EHR, in fact I don't know many implementations that use that class, but maybe others do.

I think later we'll need to define also all the VERSIONED_XXX classes in the XSD. That would help a lot on use cases that require migration of data (for example, allowing to export/import full versioned compositions between systems, for backup, for redundancy / HA, etc).

Does anyone already represented the VERSIONED_XXX classes in XSD?

GET /ehr/{ehrId}/versioned_ehr_access/version{?versionSelector}
POST /ehr/{ehrId}/versioned_ehr_access/version
POST /ehr/{ehrId}/versioned_compositions/{uid}/version{?format}
GET /ehr/{ehrId}/versioned_compositions/{uid}/version/{versionUid}{?format}
GET /ehr/{ehrId}/versioned_compositions/{uid}/version{?versionSelector,format}
GET /ehr/{ehrId}/versioned_ehr_status/version?{versionSelector}
GET /ehr/{ehrId}/versioned_ehr_status/version/{versionUid}

"version" should be "versions".

From https://github.com/openEHR/specifications-ITS/blob/master/apiary.apib

https://specifications.openehr.org/releases/ITS-REST/latest/definitions.html#definitions-adl-2-template-get

has the following inconsistent description

/definition/template/adl2/{template_id}
List all available ADL2 operational templates on the system

There are some possibilities to interpret / solve this but I'd guess it should be like above at ADL 1.4. One endpoint to list all templates and one endpoint to list a specific one (here with additional version_pattern). Hence it might should be:

/definition/template/adl2
List all available ADL2 operational templates on the system

Or is this definition like intended?

And on a side note:
https://specifications.openehr.org/releases/ITS-REST/latest/definitions.html#definitions-adl-2-template-get-1
Should have a small description. Again, maybe the same that ADL1.4 has above.

We talk about focusing on XML for a first draft version of the API specs.

1. Just want to double check if we all agree on this, please +1 if you agree.
2. Little discussion about which content type to use for requests and responses. We have text/xml and application/xml, here is some nice info about this: http://stackoverflow.com/questions/4832357/whats-the-difference-between-text-xml-vs-application-xml-for-webservice-respons

Please state which option you prefer and why for point 2.

Even though @wolandscat has pointed out that use of OBJECT_VERSION_IDs for COMPOSITION.uid values does not imply any versioning semantics as per the specifications, at least one vendor and probably more (according to slack comments) use meaningful uid values for COMPOSITIONs.

The discussion on slack did not produce an answer to the following question: "do we consider this non-standard, yet widely(?) applied practice for rest specifications".

If the answer to the above question is yes, then we need to clarify what the REST endpoint should do when

• a system id that is different than the REST endpoint's is provided as in xyz::some_other_system::1
• a version that is not equal to 1 as in xyz::rest_implementing_system::3
  Because in case of meaningful COMPOSION.uid s the above conditions imply imports rather than creating new compositions.

if the answer to the above question is no, there are still decisions to be made.

If the REST back end simply ignores the whole (OBJECT_VERSION_ID) uid or components of it, does this constitute a problem REST wise, since we're creating a resource that is different than the one provided (uid dropped)? If we're determining the identifier of the resource (via setting its uid), should not this be a PUT? RESTful design assumes POST will create the resource identifier as far as I remember

Also, @bjornna made a point regarding client side generation of UIDs which is required to commit a folder and compositions together where the folder has uids of compositions referenced. I am not sure if this is possible with the current REST api, but assuming this will be introduced later, this requirement conflicts with the behaviour in which server silently drops incoming uid values.

I tried to come up with a set of rules that satisfy all conditions above and failed, even when we assume uid has no versioning semantics. Suggestions are welcome.

Gather issues and ideas about EHR resource

@openEHR/sec versionSelector URL param is used on a lot of endpoints related to VERSIONED_XXX resources.

It can take different values of different types: string value of a VERSION unique identifier, a specific timestamp or the string LATEST_TRUNK_VERSION.

It seems to be a development shorthand, but for the official openEHR API it would be clearer to use the names of the VERSIONED_OBJECT methods to comply with the same requirements.

Example:

Current:

GET /ehr/{ehrId}/versioned_ehr_status/version/versionSelector=ISO8601_datetime|LATEST_TRUNK_VERSION|uuid

Proposed:

Using VERSIONED_OBJECT method names version_at_time, latest_trunk_version or the uid property.

(ISO8601 versionSelector)
GET /ehr/{ehrId}/versioned_ehr_status/version_at_time/{ISO8601_datetime}

(LATEST_TRUNK_VERSION versionSelector)
GET /ehr/{ehrId}/versioned_ehr_status/latest_trunk_version

(VERSIONED_XXX uid)
GET /ehr/{ehrId}/versioned_ehr_status/{uid}

During https://openehr.atlassian.net/wiki/display/spec/2016-06-30+REST+API+Meeting+notes I believe that @bjornna mentioned that one of their implementations added values (for example time-stamps) on the server-side if a mandatory field was missing.

Another option is to throw an error if mandatory things are missing. But some things (for example some timestamps) can be good to have an option to add server-side...

Yet another option could be to have some values/flags (either as metadata in the call header or some other place or inlined at places in the body) to explicitly ask the server to generate missing mandatory (and even some optional) values. A value of @now could for example be replaced with the server's current time.

Let the discussion begin...

The openEHR XSD doesn't include EHR and it's related objects and we need a schema to represent those resources on the REST API.

This should include EHR_STATUS and EHR_ACCESS.

We also need to define how to represent a collection or list of EHRs in XML. The same representation can be used for other collections, like endpoints that return collections of compositions or contributions.

Either as a part of the main REST spec or as an appendix we might want to have a look at specifying management and execution fo CDS rules via REST. There are already implementation experiences from Marand and DIPS that could give good input to discussion.

Do we all agree that the minimal endpoints and operations for the EHR resource are these?

Please double check:

1. URLs and HTTP methods (I think we all agree on this)
2. request and response headers
3. request and response payloads (body), there is another issue to discuss the specific format/structure.
4. Response HTTP status codes (please check if there are any error cases missing)

POST /ehrs creates a new EHR with an UID assigned by the server side.

Request headers:

• Content-Type: mandatory, text/xml (see #3) only for v0.1, JSON later
• Accept: might be equals to request content type to have the same syntax for request and response payloads.

Request body:

• XML document that represents a valid EHR (all the required information is specified) see #4
• Currently the apiary specs (http://docs.mytest49.apiary.io/#reference/ehr/ehr) includes information about commit audit, this was mentioned by Heath on the wiki https://openehr.atlassian.net/wiki/display/spec/openEHR+REST+APIs just want to double check if that comes from the openEHR specs or it is a feature we want to add to the REST API.

Parameters:

• I don't think we need parameters if all the information is on the body.

Response headers:

• Content-Type: mandatory, text/xml (see #3) only for v0.1, JSON later

Response body:

• the EHR resource just created, in the response content type format.

Response statuses/conditions:

• The request comes from an unauthorized source: 401 Unauthorized
• The requester doesn't have permissions to access the resource: 403 Forbidden
• The request body is empty: 400 Bad Request
• The request body doesn't contain a valid XML: 400 Bad Request
• The EHR was successfully created: 201 Created

GET /ehrs returns all the EHRs accessible by the requester

Request headers:

• Content-Type: N/A
• Accept: might be equals to request content type to have the same syntax for request and response payloads.

Request body:

• N/A

Parameters:

• offset: the returned records starts on a record number equals to the offset, allows pagination/infinite scroll implementations.
• max: maximum number of EHRs to return, empty returns all. If offset is present, max should be present.
• sort: attribute used to sort (time_created, ehr_id, system_id)
• order: asc or desc, direction of the sorting by the attribute referenced by "sort". If sort is present. order should be present.

Response headers:

• Content-Type: mandatory, text/xml (see #3) only for v0.1, JSON later

Response body:

• an list resource represented in the response content type format (see #3 for the discussion about collection or list representation in XML)

Response statuses/conditions:

• The request comes from an unauthorized source: 401 Unauthorized
• The requester doesn't have permissions to access the resource: 403 Forbidden
• The parameters don't follow the rules (e.g. sort has a value but order is not present or has an empty value): 400 Bad Request
• Pagination parameters falls outside the range of the resourse (offset = 100 with 98 EHRs): 416 Requested Range Not Satisfiable
• The response is successfully returned: 200 OK

GET /ehrs/{ehrUID} returns the EHR with ehrId={ehdUID} with accessible by the requester

Request headers:

• Content-Type: N/A
• Accept: might be equals to request content type to have the same syntax for request and response payloads.

Request body:

• N/A

Parameters:

• none

Response headers:

• Content-Type: mandatory, text/xml (see #3) only for v0.1, JSON later

Response body:

• an EHR resource represented in the response content type format.

Response statuses/conditions:

• The request comes from an unauthorized source: 401 Unauthorized
• The requester doesn't have permissions to access the resource: 403 Forbidden
• The response is successfully returned: 200 OK

Shouldn't be more RESTful to have a dimension per each method in VERSIONED_OBJECT? And leave GET /ehr/{ehrId}/versioned_ehr_status to return just uid, owner_id and time_created.

GET /ehr/{ehrId}/versioned_ehr_status/revision_history
GET /ehr/{ehrId}/versioned_ehr_status/all_versions
GET /ehr/{ehrId}/versioned_ehr_status/latest_trunk_version
GET /ehr/{ehrId}/versioned_ehr_status/version_at_time
etc.

This is similar to https://github.com/openEHR/specifications-ITS/issues/27 but focuses on the current Body of the 200 response from https://github.com/openEHR/specifications-ITS/blob/master/apiary.apib#L561-L611

Even though @wolandscat has pointed out that use of OBJECT_VERSION_IDs for COMPOSITION.uid values does not imply any versioning semantics as per the specifications, at least one vendor and probably more (according to slack comments) use meaningful uid values for COMPOSITIONs.

The discussion on slack did not produce an answer to the following question: "do we consider this non-standard, yet widely(?) applied practice for rest specifications".

If the answer to the above question is yes, then we need to clarify what the REST endpoint should do when

• a system id that is different than the REST endpoint's is provided as in xyz::some_other_system::1
• a version that is not equal to 1 as in xyz::rest_implementing_system::3
  Because in case of meaningful COMPOSION.uid s the above conditions imply imports rather than creating new compositions.

if the answer to the above question is no, there are still decisions to be made.

If the REST back end simply ignores the whole (OBJECT_VERSION_ID) uid or components of it, does this constitute a problem REST wise, since we're creating a resource that is different than the one provided (uid dropped)? If we're determining the identifier of the resource (via setting its uid), should not this be a PUT? RESTful design assumes POST will create the resource identifier as far as I remember

Also, @bjornna made a point regarding client side generation of UIDs which is required to commit a folder and compositions together where the folder has uids of compositions referenced. I am not sure if this is possible with the current REST api, but assuming this will be introduced later, this requirement conflicts with the behaviour in which server silently drops incoming uid values.

I tried to come up with a set of rules that satisfy all conditions above and failed, even when we assume uid has no versioning semantics. Suggestions are welcome.

It would be helpful to have an EHR-URI-resolving endpoint/resource standardized and possible to include in some level of the conformance spec. Likely the same conformance level as AQL since if you have implemented AQL you can do a very simple tranformation to also do EHR-URI resolution. (Implementing EHR-URI-resolution might also be a path towards AQL)

@bjornna mentioned that DIPS has a such endpoint/resource. Please add more information/experience regarding that.

Suggestions:

1. add a new resource under something like /query/path or /query/ehr-uri (since the EHR-URI syntax is essentialy a minimal query language), It should allow both GET with query string (e.g. GET /query/path?q={ehr-uri}) and POST (e.g. /query/path)
2. change GET /query/?aql={aql} to GET /query/aql?q={aql} to be consistent with POST /query/aql and to make room for other query languages,

In the above suggestions I replaced the quert-parameter name "aql" with "q" and reused the same ("q") for the EHR-URI-path since it makes a shorter uri and avoids repeating "query" and "aql"/"path" that are already clearly visible in the path. Examples of others uisng the q-convention: https://www.google.se/search?q=test https://www.bing.com/search?q=test https://stackoverflow.com/search?q=test

P.s. The old sugesstion in LiU-EEE paper (see table 1 in https://bmcmedinformdecismak.biomedcentral.com/articles/10.1186/1472-6947-13-57) to have it as a continued path after a trailing slash in the versioned object URI is bad for at least two reasons:
1, the openEHR EHR-URI-spec has changed and now includes things like /folder/ and /composition/ and a single EHR-URI-resolution service should be able to point to any of those structures - thus putting it somewhere under e.g. /compsoition/ would be a bad idea.
2. Square brackets [] etc used in EHR-URIs are considered unsafe in http://www.ietf.org/rfc/rfc1738.txt so we'd need to URL-encode them anyway and they thus fit to be sent in a GET query paramater or a post.

The documentation for the post operation (to create an EHR) suggests that if no ehr_status attribute is provided in the body, an instance should be created with is_queryable and is_modifiable fields. It then states:

All other attributes will be left empty (null)

The subject property of Ehr_Status is mandatory. The subject can have a null external_ref but I think the subject should still exist.

Reading the spec for query api: https://www.openehr.org/releases/ITS/latest/docs/query.html#query it is not clear how stored queries are created. A mention/reference to Definitions would help the reader.

The get request described here has VERSIONED_EHR_STATUS as its return type. However, the example for the content that should be returned contains the revision_history field, which is not a field of the VERSIONED_EHR_STATUS RM type.

In a slack discussion @bostjanl suggested that VERSIONED_EHR_STATUS is returned from this end point and methods of this type, where relevant are defined as individual endpoints, such as ../revision_history. This makes sense to me and I'll implement this suggestion for the moment unless SEC decides to take another direction.

In #7 Ian discussed templates, this probably deserves a separate topic, so here it is.

Some discussion starters:

1. Logically, can we assume that templated data can be comitted, retrieved and queried using the already suggested Resources and calls? (I think yes)
2. Do we also want a simplified way for submitting templated data using names/fields/attributes coming from the template (as is done in some Marand Ehrscape calls and partly similar to TDS-thinking)? (I think yes)
3. If we want simplified template usage (as in 2 above) do we then want to include that in the current API-spec file or should it be a separate spec/file/thing?

Feel free to add more discussion Points and to break this into more issues if needed.

I'm not really into API specifications but while tinkering with ehr.apib and its included composition.apib (see api-to-go) I came across following:

GET /ehr/{ehr_id}/composition/{version_uid} and GET /ehr/{ehr_id}/composition/{versioned_object_uid}{?version_at_time} are overlapping. A request like /ehr/1/composition/2 is no distinct path because they have the same set of parameters and {?version_at_time} is optional.

I don't know if this is intended or not.

Additionally I got some questions:

As one composition is defined as "One version in a VERSIONED_COMPOSITION" [RM] I don't understand why /ehr/{ehr_id}/composition/ resource is identified by version_uid rather than by its own uid.

Continuing, as I would understand it, GET /ehr/{ehr_id}/composition/{versioned_object_uid}{?version_at_time} should rather be of resource versioned_composition.
If this is correct the request could be replaced with already existing GET /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version{?version_at_time}.

This would trivially fix the issue (not really well, because remaining compositions would still be addressed by version_uid). But I'm missing the bigger scope because I'm neither really into API specs nor openEHR RM.

In addition to what was changed in fd36cc3 (regarding #69), removal of Content-Type header in 204 responses (e.g. https://specifications.openehr.org/releases/ITS-REST/Release-1.0.0/ehr.html#composition-composition-get) would make sense, too.

Some openEHR implementations (in addition to posting full "canonical" instances of RM objects) allow posting compact "diffs" that use an existing version of an object (e.g. a COMPOSITION) as a base and then just supply info on what has changed.

This issue/thread was created to discuss if/how that kind of functionality could be standardized.

One thing to consider is the desired behaviour when totally omitting an attribute in a diff call. In a canonical full form that means "no value", but in a diff format it might mean "no change". Deletion in a diff-format may require supplying the attribute and setting it's value to null.

(Issue added after discussion at meeting https://openehr.atlassian.net/wiki/display/spec/2016-06-30+REST+API+Meeting+notes)