Page Comparison

...

Method	URL	Parameters	Description	Notes
POST	/ehr	subjectId (optional): id of the subject in the external system subjectNamespace (optional): namespace of the subject id in the external system	Create a new EHR	HF: How do subjectId and subjectNamespace manifest themselves in the EHR model/resource? HF: We should allow EHR_STATUS and EHR_ACCESS objects so it is not necessary to make additional requests resulting in multiple contributions HF: We need audit details for the contribution HF: What is returned in the response?
PUT	/ehr/{ehrId}	As above	Create a new EHR with specified ehr_id	HF: Required when creating an EHR with same ehr_id as in another system
GET	/ehr/{ehrId}		Get EHR	HF: Useful to get profile of an EHR. E.g. time created, how many compositions, is there a directory, what was the last contribution etc.
DELETE	/ehr/{ehrId}		Delete an EHR	TB: this isn't possible (well not by an external REST access - it would be an internal admin operation); all you can do is mark an EHR as inactive, which would be a POST (I think) to /ehr/{ehr_id}/ehr_status/other_details/is_active or similar. But even this operation, if it succeeds, is serious - it makes it look like an EHR is deleted, so it's probably not appropriate via any externally visible REST interface. SI: In some countries the patient/client is owner of the data and it has the right (by the law) to ask for a complete (total) removal of all his data, which is more than just an inactive flag. TB: that's true, but doing the delete would require some documentation and/or special permission. I still doubt very much that this could ever be done through a visible REST interface, unless all the proof parameters were provided, and I think these would be too variable to standardise. DB: I agree with SI, this can be a requirement. The authentication/permission is a completely different issue. You could argue that the same kind documentation or special permission would be needed for creating a new composition. BL: I would leave this out of the REST API for the moment. If this is a requirement somewhere it can be performed by other means (special admin interface to the system or similar). DB: I won't leave this out, delete has a clear use case (i.e. opt-out from clinical research) ES: Seems like delete EHR is needed in some cases, so it should be system configurable, we just need to agree on what HTTP status codes/messages to return for different cases.
GET	/ehr/{ehrId}/ehr_status		Retrieve EHR_STATUS
POST	/ehr/{ehrId}/ehr_status		Update EHR_STATUS	HF: Can we create using this also? HF: We need audit details for the contribution HF: We should provide precedingVersionUid or something to support optimistic locking HF: What is returned in the response?
PUT	/ehr/{ehrId}/ehr_status/...		Update an attribute in ehr_status	TB HF: Do we really want to provide this level of updates, it may result in many contributions when multiple attributes need to be updated
GET	/ehr/{ehrId}/ehr_access		Retrieve EHR_ACCESS
POST	/ehr/{ehrId}/ehr_access		Update EHR_ACCESS	HF: Can we create using this also? HF: We need audit details for the contribution HF: We should provide precedingVersionUid or something to support optimistic locking HF: What is returned in the response?
PUT	/ehr/{ehrId}/ehr_acess/...		Update an attribute in ehr_access	TB HF: Do we really want to provide this level of updates, it may result in many contributions when multiple attributes need to be updated

Resource FOLDER

Method	URL	Description	API level	Notes
GET	/ehr/{ehrId}/directory	List folders	R1	HF: Not really a list of folders, it is the folder object
GET	/ehr/{ehrId}/directory/{folderId}	List folder content (list of links/IDs of contained objects)	R1	HF: this shouldn't be limited to single level of folders
POST	/ehr/{ehrId}/directory	Create or update a folder		HF: We need audit details for contribution HF: We should provide precedingVersionUid or something to support optimistic locking HF: What is returned in the response?
DELETE	/ehr/{ehrId}/directory	Deletes a folder		SI

Resource COMPOSITION

Method	URL	Parameters	Description	API level	Notes
POST	/compositions /ehr/{ehrId}/compositions	ehrId committer audit change type version lifecycle state commit comment	Create a new composition		HF: If we use the second URL we don't need to specify ehrId as parameter HF: should use the RM term of commit audit description rather than commit comment HF: audit parameters should be group under commit audit parameter HF: What is returned in the response?
PUT	/ehr/{ehrId}/compositions/{objectId}		Create a new composition with specified objectId		HF: Useful when you want to control the object ID
GET	/compositions/{compositionId} /ehr/{ehrId}/compositions/{compositionId}		Retrieve a composition	R1	Do we return a VERSION or a COMPOSITION here? HF: I would prefer VERSION HF: is compositionId the version UID or object ID? HF: Should be able to request version by uid, point in time or at specified contribution?
GET	/compositions/{compositionId}/version /ehr/{ehrId}/compositions/{compositionId}/version		Retrieve a VERSION		BL HF: I would prefer the reverse approach to align with RM E.g. /compositions/{compositionId}/data HF: is compositionId the version UID or object ID?
POST	/compositions/{compositionId} /ehr/{ehrId}/compositions/{compositionId}	committer audit change type version lifecycle state commit comment	Update a composition		HF: shouldn't this be PUT HF: is compositionId the version UID or object ID? HF: We should provide precedingVersionUid or something to support optimistic locking HF: What is returned in the response?
DELETE	/compositions/{compositionId} /ehr/{ehrId}/compositions/{compositionId}	committer audit change type commit comment	Delete a composition		HF: is compositionId the version UID or object ID? HF: We should provide precedingVersionUid or something to support optimistic locking

Composition format is the canonical openEHR JSON or XML format. Sample JSON and XML are attached. JSON is using the attribute names based on the RM (snake-case, i.e.: composition.archetype_details.archetype_id) and it also adds the type information - this is the extra attribute "@class" which allows such JSON to be deserialised into proper objects of the target language.

...

Method	URL	Parameters	Description	API level	Notes
GET POST	/query	aql	Execute an AQL	QL1	GET has a max limit on the query length that will be too short for some queries. (Also if using GET make sure that the server sends proper caching headers.) Should we allow both POST and GET? Added post for querying to allow loooong queries HF: I think we should support POST only
POST	/q/{query-language}		Generates a query-id and redirects to resulting resource (se rows below)	QL2	(see http://www.biomedcentral.com/1472-6947/13/57) By default the query-id could be a SHA hash of the query itself (that way repeated identical queries do not need to be re-parsed/stored) If the http-server-log is used as the main source for audit-logging, then the query needs to be stored somewhere since the content of POST is usually not logged in http-logs (The stored query could be inspected using GET q/{query-language}/{query-id}/info/ ). Storing a query (could be an ad-hoc query) for logging purposes does not mean that it needs to be converted to a stored procedure in the database. Manual or automatic routines can be used for deciding when recurring queries (same hash) should be optimized/stored. If we want to support different query languages (or query language versions) we might want urls on the form q/{QUERY_LANGUAGE}/ (examples: /q/AQL/, /q/AQL2/, /q/AQLinXQuery/) HF: Is this an specification alternative to the above or will both be included in the specification? HF: Although I like the idea of the redirect approach, I have some reservation about how javascript clients will react to these redirections HF: Should AQL be assumed in a shortform of this?
GET	q/{query-language}/{query-id}	the dynamic parameters defined when query was stored	Executes named query (using dynamic parameters)	QL2
GET	/ehr/{ehrId}/q/{query-language}/{query-id}	the dynamic parameters defined when query was stored	Executes stored query (using named parameters)	QL2	Discussion: Do we want to allow the possibility to (optionally?) split URIs for single- and multi-patient queries like this (including EHR ID in the URI)? Single-patient queries may have simpler requirements regarding security and may be more efficiently implemented in certain distributed environments. See http://www.biomedcentral.com/1472-6947/13/57 HF: I think this is useful to indicate single-ehr queries from multi-ehr queries. This should also be specified in the original query POST.

Resource CONTRIBUTION

Method

URL

Parameters

Description

Model

Notes

POST

/contribution

Atomically commits a set of changes (composition creates, updates or deletes).

Code Block

language	js

[
    {
        "action": "CREATE",
        "ehrId": "054ea32b-9ffa-4b00-ba58-a7e92be68087",
        "composition": {
			...
        }
    },
    {
        "action": "UPDATE",
        "compositionUid": "5ab5d99c-ee84-4571-9470-e5fb5002016b::default::1",
        "composition": {
			...
        }
    },
    {
        "action": "DELETE",
        "compositionUid": "1cb4e6bc-860e-4075-9fab-f3c9c113d30d::default::1"
    }
]

This call might also be under /composition resource.

...

Versions Compared

Old Version 23

New Version 24

Key

Resource FOLDER

Resource COMPOSITION

Resource CONTRIBUTION