Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 12 Next »

Initial minimal REST API

Resource EHR

MethodURLParametersDescriptionNotes
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 
GET/ehr/{ehrId}/ehr_status Retrieve EHR_STATUS 
PUT/ehr/{ehrId}/ehr_status Update EHR_STATUS 
GET/ehr/{ehrId}/ehr_access Retrieve EHR_ACCESS 
PUT/ehr/{ehrId}/ehr_access Update EHR_ACCESS 

Resource FOLDER

MethodURLParametersDescriptionNotes
GET/ehr/{ehrId}/folder List foldersR1
GET/ehr/{ehrId}/folder/{folderId} List folder content (list of links/IDs of contained objects)R1
POST/ehr/{ehrId}/folder Create a folder for this EHR 
PUT/ehr/{ehrId}/folder Update a folder for this EHR 

Resource COMPOSITION

MethodURLParametersDescriptionNotes
POST

/composition

/ehr/{ehrId}/composition

ehrId, committerCreate a new composition 
GET

/composition/{compositionId}

/ehr/{ehrId}/composition/{compositionId}

 Retrieve a compositionR1
PUT

/composition/{compositionId}

/ehr/{ehrId}/composition/{compositionId}

committerUpdate a composition 
DELETE

/composition/{compositionId}

/ehr/{ehrId}/composition/{compositionId}

committerDelete 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

MethodURLParametersDescriptionNotes

GET

POST

/query

 

aqlExecute 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} Stores query, generates 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 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 storedExecutes 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

MethodURLParametersDescriptionModelNotes
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 
R1Basic read-only. COMPOSITION+FOLDER listing and retrieval.
R2Level 2 read-only. R1 as above plus: Support for listing and retrieval of CONTRIBUTIONS, EHR_STATUS and EHR_ACCESS...
W1Basic write. Writing/updating COMPOSITIONS one by one. Creating new EHRs...
W2Level 2 write. W1 as above plus Writing several changes at once using a CONTRIBUTION...
QL1Basic Query...
QL2Level 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
  • 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

 

Comments:

  • No labels