We should always use the versioned_object_uid value for the uid_based_id parameter in the PUT https://{baseUrl}/v1/ehr/{ehr_id}/composition/{uid_based_id}. Do you see a problem with this?
For contribution, in the version you should be able to add two versions (one of the composition, another of a folder with a reference to that composition), both containing a client-generated uid . I see now that the example on the spec is using OBJECT_VERSION_ID (including the version number), but I guess it could be also HIER_OBJECT_ID. So the client has options but also responsibilities, because there are no other checks or pre-condition header, so the operation should be atomic (all or nothing).
Why would you think this would not work? What problem or issue do you see here?
In EHRServer and Atomik we have such bulk transfers but are not done via standard REST API calls since current API doesnāt support that. We call that sync API.
Our sync API copies everything to another server that supports the API, so each CDR instance could be client or server for other CDR instance, it works in a master/slave (or primary/secondary to be politically correct) way, the master is actually the data source and the secondary the destination of the data.
In āeverythingā I mean:
opts
ehrs
queries
users / organizations (if the internal identity provider is used)
contributions
versioned objects
versions
compositions
ā¦
And now that we support demographics in Atomik, we will also sync Actors, Roles, Identities, Contacts, Relationships, etc.
If I can via a POST contribution provide a composition with change type creation with a set composition .uid then It makes no sense to me way I should not be able to POST a composition with a set composition .uid and the Serve should respect that.
One reason is that Contribution is a lower level functionality comparative to ānormalā resources like Composition, Ehr, or Folder. A Contribution is also an operation in itself (an action, the equivalent of db-transaction that the client want to be executed), and as a result of that operation the Ehr gets the ātrailā as the Contribution resource. So it makes sense to me that the contribution endpoint might be loaded with more non-standard Rest functionality, while we try to keep the other ānormalā resource endpoint as āstandardā as possible (POST to create using server-side identification assignment, PUT with client-side, or update).
Another potential reason for PUT with uid is that it might be easier to check first all the precondition to engage in executing the operation without parsing/unserialiazing the payload-content. If instead youāll use POST and uid is in the payload, then you will need to consume that content first, then extract the uid, then you can assess preconditions.
Another reason would be the alignment with the way FHIR defined their http specifications.
But in any case this is still a proposal, it can still be done differently (e.g. rather POST then PUT), if there is sufficient feedback from implementations. In any case, we should keep consistency across operations: use always PUT with the id, not only for composition, but also for Ehr, templates, queries, etc. - or use always POST and with the id in the payload.
This sync API you made would be interesting perhaps also for others - do you intend to propose for openEHR specs? This is of course worth another discourse topic ā¦
My 2 cents on using PUT vs POST for predefining the composition ID.
It makes sense to use the PUT when you want to store a named object (even for creation) and to use POST when you let the server decide how to name the object.
However, the current API definition mentions the PUT to be used for updates.
Besides that, by allowing setting the composition ID through POST, but not enforcing it, means the server can still decide how to store the composition object, so itās not necessarily a violation of the POST definition.
On EHRbase side, to move forward until a new definition of the EHR REST API is released that properly defines how PUT should be used for creation, we are considering to go with respecting the composition ID in POST if itās present.
Without trying to get into the PUT/POST debate I would say one thing: REST and HTTP protocol have no built-in notion of versioning. Any architecture that does, and wants to expose CRUD calls via REST needs to decide if a āresourceā is a versioned thing, or one version of a versioning thing, and from there use POST and PUT consistently within that architecture, without worrying too much if itās not identical to other architectures.
Weāve now got compositions being imported using the POST composition using an existing composition id. We start with the old version POST and then once created we PUT any later versions, all in order. Weāre currently testing it but it seems like a good start.
Next steps are to use the Contribution API, shall I do this on a new thread? Iām also worried that we get too much into a REST debate (its not even a standard). I once got told off by Roy Fielding, and I donāt want to go back there.
I must admit Iāve learnt more about openEHR in the last few weeks than ever before
The bulk export and import of compositions(with versions) is an important part of the standard. New thread required ?
With a bit more thought, it seems to me that deciding on this at single composition level is a bit of a distraction, as most use -cases for client-generated composition uids will actually involve working at Contribution level. That does raise some more questions but might actually be easier to resolve - if nothing else the data representations in the contribution body at that level are closer to pure RM and we will be less tangled up with āRESTfulā debates
I vote for a new thread on āreplaying Contributionsā
Thanks your your input Alex.
But to be a bit clear for the scope of this comments above - it was more a discussion about what & how should we change specifications, which eventually should be followed by implementation - but in any case, this does not necessary have to be supported yet by EhrBase.
it is Birger coming in with a naive and maybe stupid question: my understanding is that even a POST of a composition is actually something like an āimplicit contributionā with only a single versioned object inside of change type create. Hence, we might also consider it as kind of an abbreviation for lazy people. Hence, I donāt understand why we should start treating them differently (Sebastian referred to contributions as "lower level functionality ").
From the point of EHRbase, I favor the approach that @vidi42 suggested.
@thomas.beale from what I understand from that interface I_ADMIN_SERVICE in the SM is that is a pull kind of service (list_contributions).
What I described above that we have a Sync API in EHRServer and Atomik is a push service: the server instance that has the data pushes the data to the other servers in the cluster, so the semantics of the Sync API are like create_ehr, create_contribution, create_composition, create_query, create_template and so on.
