search

cancerDHC / ccdh-terminology-service

CCDH Terminology and Mapping Service
3 stars 4 forks source link

Add versioning for: (i) API, (ii) specific endpoints #74

Open joeflack4 opened 3 years ago

joeflack4 commented 3 years ago

Requirements

I'm not sure if we want to do Requirement (A), (B), or both.

Requirement A: API Service versioning

Description

We have a version for the entire API, e.g.

Implementation

When do we constitute a new version? Every time we make a new deployment where any change has been made in the underlying data model?

What kind of versioning system to use? Simply incrementing integers?

Requirement B: Individual versioning to all endpoints

Description

Add versioning param to all endpoints. If a given resolved endpoint changes, it should be versioned up.

Implementation

For every endpoint, we would have the ability to tack on a /versions and /versions/<NUM> endpoint to each. Default without adding will be to add latest version.

Examples

Example 1

Before https://terminology.ccdh.io/models/CRDC-H/entities/Specimen/attributes/tumor_status_at_collection

After https://terminology.ccdh.io/models/CRDC-H/entities/Specimen/attributes/tumor_status_at_collection

https://terminology.ccdh.io/models/CRDC-H/entities/Specimen/attributes/tumor_status_at_collection/versions

https://terminology.ccdh.io/models/CRDC-H/entities/Specimen/attributes/tumor_status_at_collection/versions/2

joeflack4 commented 3 years ago

@ShahimEssaid Let me know if this is what you are thinking is a good way to do versioning for our endpoints.

@jiaola Any thoughts? If not that is fine.

gaurav commented 3 years ago

It seemed to me that Chris C and Shahim had reached an interesting point in this discussion when I had to interrupt them so we could focus on this pilot, which is:

  1. Do we want to include terminologies in the model, in which case we will either need:
    • A relatively static model that changes rarely, so that CRDC data consumers don't need to change their software very often, or:
    • A model that changes "frequently" (at least in terms of the terminologies it uses) so that it always reflects the latest terminologies, and we assume that most CRDC data consumers will stay a few versions behind the latest version until they put in the effort to catch up.
  2. Or do we want to keep the terminologies out of the model somehow?

If we go with the first option, then I think we can version our terminology services alongside the model -- i.e. if someone looks up the meaning of a particular term for CRDCH v1.0.1, we will guarantee to always return a consistent result, although that same term might be reported as not a permissible value for CRDCH v1.0.2. If we go with the second option, then I think we would need to record some sort of version from the terminology itself: I'm not sure how to do that with NCIt, but caDSR CDEs and most ontologies have version numbers, so it should all be doable... somehow.

I assume this will be relevant to the big CodeableConcept/enumerations discussion currently going on.

joeflack4 commented 3 years ago

Hey Gaurav! Big thanks for adding your thoughts here and for your prodding at the meeting.

I like choice (1.b).

If we go with (1.b), perhaps I'll play a more direct role in getting those term codes into the ccdhmodel.

And I'm thinking that we can version individual changes to data elements / terminologies with integers. For the API / model itself, perhaps semver would make more sense since we will be updating more frequently.

gaurav commented 3 years ago

And I'm thinking that we can version individual changes to data elements / terminologies with integers. For the API / model itself, perhaps semver would make more sense since we will be updating more frequently.

True! If you have other thoughts about versioning the model itself, please add them to https://github.com/cancerDHC/ccdhmodel/issues/93.