Two GET COMPOSITION endpoints have the same structure and different semantics


In the current spec we have:

GET /ehr/{ehr_id}/composition/{version_uid}

GET /ehr/{ehr_id}/composition/{versioned_object_uid}{?version_at_time}

Since the version_at_time on the second endpoint is a normal parameter, not part of the URL, both endpoints have the same structure, which is impossible to distinguish at the implementation level.

The problem is the semantics of the version_uid and the versioned_object_uid are different, also have a different internal structure, so we have two endpoints that depending on the internal format of part of the URL might return different results, but for the same resource (COMPOSITION).

As a general approach for IDs, best practice is to consider those are opaque, meaning no internal processing should be done and the whole ID should be considered as a unique pointer to a resource. With the current spec this is not possible.

About semantics for REST, if COMPOSITION is the resource, what is considered an ID of the resource should be used in the URL, so IMO composition/version_uid is the correct one. And the other endpoint should be really resolved for the VERSIONED_OBJECT resource. So instead of:

GET /ehr/{ehr_id}/composition/{versioned_object_uid}{?version_at_time}

We should use what we already have to get a VERSION<COMPOSITION> inside the VERSIONED_OBJECT:

GET /ehr/{ehr_id}/versioned_composition/{versioned_object_uid}/version{?version_at_time}

The proposal is to remove the endpoint GET /ehr/{ehr_id}/composition/{versioned_object_uid}{?version_at_time} because we already have another way to get a version at time in the spec, and because it conflicts with the other endpoint in structure GET /ehr/{ehr_id}/composition/{version_uid}




Pablo Pazos