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}




Matija Polajnar
May 20, 2019, 5:58 AM

The versioned_composition URL returns a result wrapped into a version wrapper, so it is not the same.

The file links analogy was meant to persuade you that composition is a composition (a single resource) and although the same is available under multiple “names” (IDs), it is not necessary (or desirable) to put them under two different “directories” (URL paths).

The “query string in path” and “arbitrary path” (or “overlapping path”) referred to Jake Smolka’s comment.

Pablo Pazos
May 20, 2019, 6:04 AM

Yes, is not the same, but the is the compo, so accessing the compo is trivial. What I meant is the goal of the endpoint already exists in another endpoint, not that the other endpoint returns exactly the same data byte by byte, but that the data is there.

Matija Polajnar
May 20, 2019, 6:11 AM

Well yes, but it requires additional processing (sic) on the client side.

I forgot to mention that you are technically correct regarding version id and versioned object id being two distinct classes and if implementation strictly follows this model, there is processing needed on the endpoint implementation to distinguish between the two.

Pablo Pazos
May 20, 2019, 4:36 PM

I forgot another thing, the version_uid: OBJECT_VERSION_ID, is not actually an id for COMPOSITION, is an id for VERSION<COMPOSITION>.

It was mentioned on the SEC to use that value in the COMPOSITION.uid, that is why it works (only) for who implemented it that way. This is currently not part of the specs, so we actually need to use version_uid to get VERSION not COMPOSITION.

I mentioned that on the SEC, if we are going to implement this, it should be in the spec. The ticket is on Jira

Matija Polajnar
May 21, 2019, 7:02 AM

I agree, see comment I just added to SPECPR-322.


Pablo Pazos