Page Comparison

...

Method

URL

Parameters

Description

Notes

POST

/ehrs

subjectId (optional): id of the subject in the external system
subjectNamespace (optional): namespace of the subject id in the external system
committer
audit change type
commit audit description

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

BL: Good idea.

HF: We need audit details for the contribution

HF: What is returned in the response?

BL: At the moment only:

Code Block
{ "meta": { "href": "http://localhost:8082/rest/v1/ehr/f77f9b4a-cfda-414d-aa6c-4f78bcac7601" }, "action": "CREATE", "ehrId": "f77f9b4a-cfda-414d-aa6c-4f78bcac7601" }

HF: What is the purpose of meta and action? Shouldn't we use HTTP headers for these?

HF: Why have we change the URL to /ehrs? The resource is an EHR.

PUT

/ehrs/{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

/ehrs/{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

/ehrs/{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

/ehrs/{ehrId}/ehr_status

Retrieve EHR_STATUS

POST

/ehrs/{ehrId}/ehr_status/{versionUid}

committer
audit change type
commit audit description

Update EHR_STATUS

HF: Can we create using this also?

BL: Do we need to - would it not be better to create a default status and access when creating EHR (or use the provided ones in the EHR create call body).

HF: If that is our suggested approach then fine, but this needs to be specified.

HF: We need audit details for the contribution

HF: We should provide precedingVersionUid or something to support optimistic locking

BL: Added versionUid.

HF: What is returned in the response?

BL: What would you have in response?

HF: Is version uid the new version UID or preceding version uid? The proposed URL would suggest we are posting to this version, not replacing it.

HF: I think preceding version uid should be represented as a HTTP If-Match header rather than in the URL. This keeps urls simple and clean.

HF: What is returned in the response?

BL: What would you have in response?

HF: I would suggest we just need HTTP status and headers Content-Location (version specific URL, although we don't have one) and ETag (new version uid)

HF: FHIR uses the HTTP Prefer header to allow the client to specify return minimal or representation. The latter would return the new version of the resource. The server can decide how it responds if it is not specified.

PUT

/ehrs/{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

/ehrs/{ehrId}/ehr_access

Retrieve EHR_ACCESS

POST

/ehrs/{ehrId}/ehr_access/{versionUid}

committer
audit change type
commit audit description

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

/ehrs/{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

...

Method	URL	Description	API level	Notes
GET	/ehrs/{ehrId}/directory	Get folder object	R1	HF: Not really a list of folders, it is the folder objectDo we want to indicate that this is the root directory folder?
GET	/ehrs/{ehrId}/directory/{folderId}/...	Get folder subfolder object	R1	HF: this shouldn't be limited to single level of foldersDo we want to indicate that this is subfolder?
POST	/ehrs/{ehrId}/directory/{versionUid}	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	/ehrs/{ehrId}/directory/{versionUid}	Deletes a folder		SI

...

Method

URL

Parameters

Description

API level

Notes

POST

/compositions

/ehrs/{ehrId}/compositions

ehrId
committer
audit change type
version lifecycle state
commit audit description

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?

BL: response is very simple:

Code Block

{
  "meta": {
    "href": "http://example.domain.com:8082/rest/v1/composition/bddcedc8-46cc-4df6-8b1a-b05534235f17::example.domain.com::1"
  },
  "action": "CREATE",
  "compositionUid": "bddcedc8-46cc-4df6-8b1a-b05534235f17::example.domain.com::1"
}

PUT

/ehrs/{ehrId}/compositions/{objectId}

Create a new composition with specified objectId

HF: Useful when you want to control the object ID

GET

/compositions/{compositionId}
/ehrs/{ehrId}/compositions/{compositionId}

Retrieve a composition

R1

Do we return a VERSION or a COMPOSITION here?

HF: I would prefer VERSION

BL: I would prefer a different resource returning versions

HF: Perhaps that is the difference between /composition/{compositionId} and /ehr{ehrId}/compositions/{compositionId}, or are you suggesting something like /version/{uid}?

HF: I would prefer VERSIONBL: I would prefer a different resource returning versionsHF: is compositionId the version UID or object ID?

BL: we could have both - one returns exact version specified, the other latest one?

HF: Should be able to request version by uid, point in time or at specified contribution?

BL: Good idea - can you suggest parameters?

version by uid, point in time or at specified contribution?

BL: Good idea - can you suggest parameters?

HF: We use the idea of versionTime, which may be symbolic such as LATEST_TRUNK_VERSION, contribution uid or timestamp

GET

/compositions/{compositionId}/version
/ehrs/{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}

/ehrs/{ehrId}/compositions/{compositionId}

committer
audit change type
version lifecycle state
commit comment

Update a composition

HF: is compositionId the version UID or object ID? If version UID then it should be PUT. Having said that, FHIR uses PUT for update using an object ID.

BL: I think it should be version uid as it then also gives us optimistic locking

HF: We should provide precedingVersionUid or something to support optimistic locking, this could be done using the HTTP If-Match header

HF: What is returned in the response?

DELETE

/compositions/{compositionId}

/ehrs/{ehrId}/compositions/{compositionId}

committer
audit change type
commit comment

Delete a composition

HF: is compositionId the version UID or object ID?

BL: I think it should be version uid as it then also gives us optimistic locking

HF: We should provide precedingVersionUid or something to support optimistic locking

...

Method

URL

Parameters

Description

Model

Notes

POST

/contributions

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.

HF: Although the RM doesn't explicitly state this, I think contributions should be related to an EHR. E.g. /ehr/{ehrId}/contributions

HF: Where multi-ehr contributions are required, we may consider a transaction mechansim

HF: The contribution resource should align more with the RM such as using a cut down representation of the ORIGINAL_VERSION including attributes such as lifecycle_state, preceding_version_id, change_type, data.

BL: Even in the current call - where multiple EHRs are concerned contributions should be created for each EHR separately - but the whole operation should still be transactional - so all or nothing. I do agree it would also be nice to have a call with /ehr/{ehrId}/ prefix. Perhaps the name contribution is not right although I hardly imagine somebody would want to POST contributions.

HF: /contributions makes sense in the context of /ehr/{ehrId}/contributions. If there remains a stand alone CONTRIBUTION resource then /contribution would still make sense.

Implementation levels (suggestion)

...

Versions Compared

Old Version 29

New Version 30

Key

Implementation levels (suggestion)