Overview for REST API work to be done - for Release 1.1.0 or 2.0.0
Additions or changes requested
overall
https://openehr.atlassian.net/browse/SPECITS-58
it supporting flat and json/xml, controlling with Accept header
/definition/adl1.4/{templateId}/example[?type={filterType}&detailLevel={detailLevel}]
filterType = input|output
it contains a larger set of data, but not necessary the largest, given values for some optional fields
detailLevel = min|medium|max
can be used for validation and developments
serializing errors:
investigate if RFC is in use -https://datatracker.ietf.org/doc/html/rfc7807 ( is also using it)
try to align if possible with FHIR
we should not use RM type
EHR
Add
/ehr/{ehr_id}/folder
and/ehr/{ehr_id}/versioned_folder
Add missing EHR_ACCESS ?
similar to EHR_STATUS
we will mention in specs that this resource is created automatically by the system when the EHR is created, and is not possible to add it in the payload of EHR creation (like we do for EHR_STATUS)
fix EHR summary - not “very” restful => this is a breaking change
Definitions
=> admin?
should we support also archetypes? => no, or at least is low prio, perhaps next version
are we going to support (reading) terminology / value sets? => no, this is the job of terminology service
add alternative /definition/adl2/{archetype_id_matcher} and deprecate /definition/adl2/{template_id}/{version_pattern} - potentially breaking change
query type => add “formalism” in text
(new endpoint) Demographics / Registry
group is ok to do the following, in a separate api page, but it should remain optional, not be required by conformance testing
ACTOR is abstract, so we’ll need concrete types
Sync SM specs
Add
/registry/person/{version_uid}
and/registry/versioned_person/{versioned_object_uid}
Add
/registry/agent/{version_uid}
and/registry/versioned_agent/{versioned_object_uid}
Add
/registry/group/{version_uid}
and/registry/versioned_group/{versioned_object_uid}
Add
/registry/organisation/{version_uid}
and/registry/versioned_organisation/{versioned_object_uid}
Add
/registry/role/{version_uid}
and/registry/versioned_role/{versioned_object_uid}
Add
/registry/party_relationship/{uid}
Add also
/registry/contribution/{contribution_uid}
similar to/ehr/{ehr_id}/contribution/{contribution_uid}
Initially we discussed about /registry
endpoint but we'll keep this for later (a new RM Entity?) and in the meanwhile we'll use /demographic
as that matches current Demographic IM component name.
see also Pablo’s proposal and
TAGs
see tags suggestion (todo @Sebastian Iancu )
POST|PUT|GET|DELETE /api/v1/ehr/{ehr_id}/(composition|folder..)/{version_uid}/tags[/{tag_key}[/{target_path}]] - Update tags on a COMPOSITION (and FOLDERs?). Existing tags will be replaced
(question: does the tags should also consider target_path
? do we need to support case where more tags with same key
is used for same target
but with different target_path
?)
perhaps querying/filtering of tagged objects can be done like:
GET /api/v1/ehr/{ehr_id}/(composition|folder..)?tags[key]=value
adding tags on creation-time on compositions via headers in case of committing composition
resource, and inline inside the contribution
resource.
GET /api/v1/ehr/{ehr_id}/tags - Get all tags currently defined in the CDR for the current EHR.
Dips:
GET /api/v1/tag/keys - Get all tags keys currently defined in the CDR (DIPS variant).
Seref: maybe support tag incrementally, i.e. allow it to be used in Composition endpoint but not allow the full constraint semantics for tag to be used for aql because it may make it difficult for the implementers to apply the tag constraint to aql results (what if the tag.target_path is not in the SELECT OF AQL?)
Sidharth: What will happen if a composition is created with a tag atomically during POST, but is updated using PUT without the tags using the API
Sidharth/Erik: Strategy for filtering based on tags:
OR tags: composition?tag=key1,key2
AND tags: composition?tag=key1&tag=key2
What should happen when we update a composition and the tags are pointing to a specific (previous) version, or to a path that does not exists inside the composition
Erik: perhaps we should add an invariant, stating that a path should be only used when the target is a version<T>.
Erik: should we support logic not() on query params?
(new endpoint) Admin
how should we deal with admin required functionality, e.g. destroy EHR, Compositions, Actors, etc ? Need a specific endpoint /admin or use DELETE action over resources, assuming ACL permits ?
DELETE /admin/ehr/{:ehr_id}
DELETE /admin/ehr/{:ehr_id}/composition/{:composition_id}
see
later (less prio) also merge, unmerge, move content
delete template is problematic, if is “in use” - but on the other hand this is an admin endpoint, so it should be fine
export / import
/admin/ehr/exports
/admin/ehr/import
configure the export/import task scope with a payload (e.g. all-ehrs, subset of ehrs based on their ehrIds, “some compositions”)
background tasks - consider polling
need to define what will be the format for this dump - zip? (Seref:) sqlite? (Severin:) csv or json?
we will need to define schema for this export format
Ian: see Josh Mandel on dumping ehr-data
do we need something like ehr_extract ?
self-contained package, including templates, archetypes; maintaining cross references, versioning, contribution
import should work on existing populated CDR
what if template or other data already exists?
Alex: consider keycloak import/export strategies
consider flag to anonymize data upon export
can be used for data migration from one CDR to another, or another version
Ian:
merging EHRs
parameters: source ehr-id and target ehr-id
Sebastian: it will move data from old ehr to new ehr
Sebastian: might be possible to use ehr_status to indicate that source ehr was merged, perhaps use folders or tags to mark the merged content
Alex: use ehr_status other_details or feeder_audit to indicate merging information
see also
Erik: I wonder if merge is a variant action of moving data
better has also
unmerge
andmove
operationshow to deal with merge-conflicts ? imagine merging persisting compositions, episodes, demographic data, duplicates tags, etc
archiving/shredding Person/EHR (partial, cohort)
system?
Bugs
- might be a breaking change
but also to other places
Headers
Audit headers with JSON Simplified Format
converting location response header to content-location (see ) => breaking change
Pablo: an idea to backport functionality from v2 to v1 but do it with right headers, we should actually deprecate the “wrong” headers and already add the new-future headers
Missing (specification) details
try with prefer=identifiers
discussed on discourse, we should allow it (todo check), no need to do anything on REST level
Others
Reformat Introduction
Conformance info
IANA
Reformat and reorganize
Overall Layout
sync with SM, add UV models (relaxed RM)
authentication endpoint => (still) no needed
audit service endpoint => not prio, perhaps not part of rest api
(cds) hooks => if Cambio can help with a proposal then it can be included, but we should also look into generalized triggers
simplify, consolidate and reuse yaml-blocks while building up specs
All issues
The followings are all Jira issues scheduled for REST API Release 1.1.0: