Issue/Enhancement- Make the expand option in the REST interface consistent with other options

[colin-e-nhsd]

SnowOwl: 7.8.4
Endpoint: /snomed-ct/v3/{path}/concepts

Describe the bug
The concepts endpoint has an expand option. This option accepts a parameter defining multiple choices selected from any combination of the values: fsn(); pt(); and descriptions()

Issues:

1. The doc page does not define the syntax for the single string parameter (it accepts comma-delimited options)
2. The interface accepts multiple string parameter values in any order, therefore it should be of type string array (not a single delimited string) to be consistent with other options in the interface, e.g. ancestor
3. The presentation of the allowed parameters as "function like" i.e. with parentheses is misleading. They are not functions and they don't accept parameters. These are column or attribute names (or maybe attribute synonyms) and are therefore just plain fsn etc. I think.

Expected / Preferred behavior

1. Give expand a string array parameter type like the other multi-value options
2. Make the choices plain column names (no parentheses), unless they are ultimately going to behave like functions and allow parameter values to be supplied in the parentheses for each option.

Version

• Snow Owl Version: 7.8.4
• Elasticsearch Version (external): ?

[cmark]

Hi @colin-e-nhsd,

Yes, this is something we would like to enhance in the future to make the expansion API easier to use and accept array of values as well, not just a single String value.
We will definitely schedule this for an upcoming release.

The presentation of the allowed parameters as "function like" i.e. with parentheses is misleading. They are not functions and they don't accept parameters. These are column or attribute names (or maybe attribute synonyms) and are therefore just plain fsn etc. I think.

Regarding the function-like behaviour. This is actually by design and some of the parameters that are accepted by the expand query parameter are actually allow arguments to be defined.
For example: descendants() expansion accepts three arguments:

• direct: true|false - whether to return direct descendants, aka children, or return concepts from the entire subtree
• limit: integer - the number of descendants to return
• expand: for nested expansion (eg. to expand the fsn() of the descendant concepts)

This is similar to GraphQL APIs, where you can create a nested query.

A great example would be to fetch all information for a concept in a single request:

curl localhost:8080/snowowl/snomed-ct/v3/<path>/concepts/<conceptId>?expand=definitionStatus(expand(pt(),fsn())),module(expand(pt(),fsn())),pt(),fsn(),descriptions(expand(acceptabilities(expand(acceptability(expand(pt())),languageRefSet(expand(pt(),fsn())))),type(expand(pt())),module(expand(pt())),caseSignificance(expand(pt())))),relationships(expand(type(expand(pt(),fsn())),destination(expand(pt(),fsn())),module(expand(pt(),fsn())),characteristicType(expand(pt(),fsn())),modifier(expand(pt(),fsn()))))

This returns a Concept JSON object with all necessary information expanded (description with types/modules/etc, relationships with types/destinations/etc, concept pt/fsn) to display a detail page for it. It even supports Locale based display label expansion by using the Accept-Language header.

Regards,
Mark

[cmark]

Hi @colin-e-nhsd,

This feature is available in the latest 8.0.0 release. Feel free to check it out.

Cheers,
Mark