New call proposals are in blue.
API levels in green.
Initial minimal REST API
Resource EHR
Method | URL | Parameters | Description | Notes |
---|---|---|---|---|
POST | /ehr |
| Create a new EHR | |
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. | |
GET | /ehr/{ehrId}/ehr_status | Retrieve EHR_STATUS | ||
POST | /ehr/{ehrId}/ehr_status | Update EHR_STATUS | ||
PUT | /ehr/{ehrId}/ehr_status/... | Update an attribute in ehr_status | TB | |
GET | /ehr/{ehrId}/ehr_access | Retrieve EHR_ACCESS | ||
POST | /ehr/{ehrId}/ehr_access | Update EHR_ACCESS | ||
PUT | /ehr/{ehrId}/ehr_acess/... | Update an attribute in ehr_access | TB |
Resource FOLDER
Method | URL | Parameters | Description | API level | Notes |
---|---|---|---|---|---|
GET | /ehr/{ehrId}/directory | List folders | R1 | ||
GET | /ehr/{ehrId}/directory/{folderId} | List folder content (list of links/IDs of contained objects) | R1 | ||
POST | /ehr/{ehrId}/directory | Create or update a folder | |||
DELETE | /ehr/{ehrId}/directory | Deletes a folder | SI |
Resource COMPOSITION
Method | URL | Parameters | Description | API level | Notes |
---|---|---|---|---|---|
POST | /compositions /ehr/{ehrId}/compositions |
| Create a new composition | ||
GET | /compositions/{compositionId} | Retrieve a composition | R1 | Do we return a VERSION or a COMPOSITION here? | |
GET | /compositions/{compositionId}/version
| Retrieve a VERSION | BL | ||
POST | /compositions/{compositionId} /ehr/{ehrId}/compositions/{compositionId} |
| Update a composition | ||
DELETE | /compositions/{compositionId} /ehr/{ehrId}/compositions/{compositionId} |
| Delete a composition |
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.
Authentication, sessions should be up to the implementation.
Resource QUERY
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 |
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/) | |
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 |
Resource CONTRIBUTION
Method | URL | Parameters | Description | Model | Notes |
---|---|---|---|---|---|
POST | /contribution | Atomically commits a set of changes (composition creates, updates or deletes). | [ { "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. | |
Implementation levels (suggestion)
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.
Level | |
---|---|
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... |
QL1 | Basic Query... |
QL2 | Level 2 Query. Named/identified queries with dynamic parameters (allows stored procedures and other optimizations). |
CDS1...? | Clinical Decision Support? |
A system could for example support R1+QL1 another might support R2+W2
TODO-list
- define & describe return model format for all calls (JSON & XML)
- ...including MIME-types suggested by DIPS: application/vnd.openehr+xml or application/vnd.openehr+json
- ...including MIME-types suggested by DIPS: application/vnd.openehr+xml or application/vnd.openehr+json
- define all required parameters (esp commit calls are missing changetype, lifecycle status, ...)
- define additional resources - FHIR like archetype-based resources, conformance?, ...
- Generate machine-readable representation of the REST interface (WADL etc)
Background info/resources
EHRScape API https://www.ehrscape.com/reference.html and https://www.ehrscape.com/api-explorer.html
Applying representational state transfer (REST) architecture to archetype-based electronic health record systems (Erik Sundvall et. al.): http://www.biomedcentral.com/1472-6947/13/57
Corresponding test implementation (LiU-EEE) available at https://github.com/LiU-IMT/EEE/,
html for the index page of the demo server https://github.com/LiU-IMT/EEE/blob/master/src/main/resources/www-file-root/index.html
Possibly interesting java Restlet routers: https://github.com/LiU-IMT/EEE/tree/master/src/main/java/se/liu/imt/mi/eee/ehr
- Ian M has a Word doc [please link/attach it here]
- Koray: Amundsen 'collection type'
- PhD thesis of Roy Fielding, where the REST-architecture was defined and motivated: Architectural styles and the design of network-based software architectures. https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
Comments: