/ehr/: composition/{version_uid} and composition/{versioned_object_uid} overlapping about specifications-its-rest HOT 9 CLOSED

I will try to explain my understanding of the two endpoints.

There is a VERSIONED_OBJECT
which has 1..* VERSIONS

Each VERSION have an UID of type OBJECT_VERSION_ID. This identifier is defined as follows:

Unique identifier of this VERSION, in the form of an {object_id, a version_tree_id, creating_system_id} triple, where the object_id has the same value as the containing VERSIONED_OBJECT’s uid.

The format of OBJECT_VERSION_ID is as follows: 'object_id'::'creating_system_id'::'version_tree_id'
An example of an 'object_id' might be: b49f6a34-e4cf-4383-b62c-fdda5ed41596::com.hospital4::1

Where:

• b49f6a34-e4cf-4383-b62c-fdda5ed41596 is the 'object_id'
• com.hospital4 is the system_id
• 1 is the version_tree_id

Which means

GET /ehr/{ehr_id}/composition/{version_uid} will be replaced with
GET /ehr/{ehr_id}/composition/b49f6a34-e4cf-4383-b62c-fdda5ed41596::com.hospital4::1
// Returns a specific versioned Composition.

GET /ehr/{ehr_id}/composition/{versioned_object_uid}{?version_at_time}
will be replaced with
GET /ehr/{ehr_id}/composition/b49f6a34-e4cf-4383-b62c-fdda5ed41596
and returns the currently latest version

If you use the version_at_time selector an example might be like this:
GET /ehr/{ehr_id}/composition/b49f6a34-e4cf-4383-b62c-fdda5ed41596?version_at_time=2017-06-01T10:00:00.000+01:00

Which returns the currently latest version at first of june 2017

So to summarize this:
The server MUST parse the path_parameter to tell what kind of UID is given. Based on that the server MUST return the correct object/instance.

from specifications-its-rest.

@jakesmolka, to add something more to what @bjornna already explained:

You should see COMPOSITION as the 'main' resource here. Inside an openEHR system COMPOSITION should be persisted in versioned fashion - i.e. you should have versions in time that are identifiable, all representing a history of the latest one (the current one). All those versions and their revision metadata can be found in the VERSIONED_COMPOSITION.

When you need to refer to a specific version or the COMPOSITION, you should use {version_uid} (e.g. b49f6a34-e4cf-4383-b62c-fdda5ed41596::com.hospital4::1).

When you need to refer to the latest one, and you don't know the exact {version_uid}, you can use the {versioned_object_uid} (e.g. b49f6a34-e4cf-4383-b62c-fdda5ed41596). You can also get a the 'snapshot' at a specific time as described by @bjornna .

A VERSION is just an wrap around COMPOSITION and is used in the versioning technique.
If you need revision history metadata, you can use the VERSIONED_COMPOSITION to get all VERSIONS.

These things are described more extensively here: http://www.openehr.org/releases/BASE/Release-1.0.3/docs/architecture_overview/architecture_overview.html#_versioning_2.

If you have more questions, you can ask them on technical mailinglist (http://lists.openehr.org/mailman/listinfo/openehr-technical_lists.openehr.org).

from specifications-its-rest.

from specifications-its-rest.

@bjornna IMO inferring types from formats is not a good practice, but technically works.

I would prefer to use dimensions in the URL like:

GET /ehr/{ehr_id}/composition/version_uid/b49f6a34-e4cf-4383-b62c-fdda5ed41596::com.hospital4::1

and

GET /ehr/{ehr_id}/composition/versioned_object_uid/b49f6a34-e4cf-4383-b62c-fdda5ed41596

That allows to keep separated endpoints. The other alternative is just to specify everything as query string parameters, and have one endpoint GET /ehr/{ehr_id}/composition that accepts all the parameters. We might need to specify some extra rules about using parameter combinations.

Ideas?

from specifications-its-rest.

I agree Pablo but for a new developer this seems quite complex.

Is there an appetite for making version_uid the 'canonical form'?

could we do
GET /ehr/{ehr_id}/composition/b49f6a34-e4cf-4383-b62c-fdda5ed41596::com.hospital4::1

and

GET /ehr/{ehr_id}/composition?versioned_object_uid=b49f6a34-e4cf-4383-b62c-fdda5ed41596

from specifications-its-rest.

Please try to stick to the original topic/question; besides that, several proposals on
GET /ehr/{ehr_id}/composition/...
were already discussed and final format was already agreed for v1.0; until it reaches stable state, we should just operate small changes.

from specifications-its-rest.

@sebastian-iancu the only issue I see with the current endpoints is that implies all implementers need to infer the type from the format. I think we didn't detected that on the SEC meetings, that is why I proposed an alternative that is really only to avoid URL collisions and type inferring from the format.

If everyone else +1 going ahead with the current endpoints, it's OK for me, but we need to address the type inferring on the documentation. Currently there is no info about that https://rawgit.com/openEHR/specifications-ITS/master/docs/ehr.html#composition-composition-get

from specifications-its-rest.

I also think that for release 1 (and possibly later too) we should stay with current endpoint.

from specifications-its-rest.

Pablo, I agree with your principle (very much), but I think that this is a special/edge case and would prefer it the way it is currently specified. Different endpoints work as well of course.

from specifications-its-rest.