Clarify the two enumeration endpoints

[gaurav]

The CCDH Terminology Service currently has two enumeration-related endpoints:

• https://terminology.ccdh.io/docs#/CRDC-H%20and%20CRDC%20Node%20Models/get_model_entity_attribute_enums (note: when given CRDC-H.Subject.cause_of_death, this currently returns only the name of this enumeration).
• https://terminology.ccdh.io/docs#/Enumerations/get_enumeration (note: when given CRDC-H.Subject.cause_of_death, this returns a list of permissible values for this enumeration).

Could you please clarify what the difference is between these two endpoints?

[joeflack4]

@gaurav I haven't figured out any intended difference either. As mentioned a couple months ago, I'm going to be merging these endpoints, but I just haven't gotten to it yet. There is an existing issue or two related to that, though. There seems to little of use to https://terminology.ccdh.io/docs#/Enumerations/get_enumeration, but what little remains, I plan to add such functionality to the other endpoint by introducing additional optional parameters (hopefully no more than 1 additional param).

[gaurav]

As mentioned a couple months ago, I'm going to be merging these endpoints, but I just haven't gotten to it yet. There is an existing issue or two related to that, though.

Should we change sheet2linkml to target /models/{model}/entities/{entity}/attributes/{attribute}/enumerations, then? This would also solve the problem of having one API endpoint randomly using YAML instead of JSON :)

There seems to little of use to https://terminology.ccdh.io/docs#/Enumerations/get_enumeration, but what little remains, I plan to add such functionality to the other endpoint by introducing additional optional parameters (hopefully no more than 1 additional param).

If you're thinking of the value_only field, I don't think sheet2linkml needs that: I think Dazhi implemented that because he thought I would directly inject the returned YAML into the ccdhmodel schema file, but sheet2linkml has always parsed the returned data before using it. So we can skip the concept identifiers if we don't want to use them. We could discuss this on the Terminologies call today if you like!

[joeflack4]

We just discussed this on the call, but just commenting here:

The main endpoint I wanted you guys to use is the /enumerations/model/entity/attribute endpoint, but as we discussed, the plan is to keep both of these endpoints and have them return the exact same content.

Regarding parameterization, I wasn't talking about the value_only field, but was referring to any unique functionality of the endpoint. As we discussed, we determined that the only unique value offered by the endpoint you referred to is that it can offer a response in yaml. We determined that we don't need to keep that functionality, but it wouldn't hurt.

[gaurav]

Reopening as a reminder that you are planning to deprecate https://terminology.ccdh.io/docs#/Enumerations/get_enumeration, but -- since the other endpoint isn't working -- sheet2linkml shouldn't switch to using that endpoint yet.

[joeflack4]

Hey @gaurav. Thanks, but I already have an existing ticket for that endpoint: #100

Progress on a lot of these issues has been slow, and I did not mark this one as urgent, but I can bump it up in urgency / tackle it by a certain timeframe as well if you like.