Overview for REST API work to be done - for Release 1.1.0 or 2.0.0

Additions or changes requested

overall

EHR

  • Add /ehr/{ehr_id}/folder and /ehr/{ehr_id}/versioned_folder https://openehr.atlassian.net/browse/SPECITS-63

  • 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 and move operations

    • how 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:

key summary type created updated priority status resolution acceptance
Loading...
Refresh