Create new API parameter for user to specify data version

[torimcd]

Acceptance Criteria: User can indicate which data version they want results for. Hydrocron returns data belonging only to the collection version that is associated with the data version they indicated.

Some questions to discuss/confirm before starting:

What do we use as the data version indicator? Options that have been raised include:

• collection shortname
• concept id
• version number (eg 1.0, 2.0,...)
• version letter (version_c, version_d,...)

What should the request parameter be? This depends on what we choose for the indicator

• collection_name
• collection_id
• data_verson

Should this parameter be required?

[nikki-t]

I like the idea of using collection_name as the query parameter with a value of collection shortname since users are used to working with collection shortnames doing Earthdata Search and CMR queries.

I also like the idea of keeping things simple and going with a data_version query parameter with a value of version letter or version number.

Thinking about the end user, how do they find this info (collection shortname or data version)? Which is easiest for them to find and/or more commonly used? Would it make sense to have both a version and a collection short name parameter?

I am inclined to not make this parameter required so that we do not introduce a breaking change but can be convinced that this is not a good idea! I think we should default to returning the Version C data until Version D data is available then we should default to Version D even though it may start out with only forward stream data. This way we can retire the version C data when appropriate and not impact the default.

We can document this decision for users so that they can figure out how to handle the switch. Either way we will need to broadcast the version change as it will require our end users to make some decisions on when to pull in the new version D data.

[torimcd]

I agree. After talking with Jack and going back through the documentation I think that what we are really asking users to tell us here is what collection they want to pull data from, so we should just use collection shortname. That also makes it more straightforward for us to map table to collection. I think there will be users who only interact with SWOT data through hydrocron (ie students) who may not otherwise interact with the DAACs, and they may not be familiar with the concept of a collection shortname, but I think there's more risk for confusion with data processing version (CRID) if we try to abstract that away too much.

This means we probably want to support both parent and subcollection shortnames, ie a user could request:
&collection_name=SWOT_L2_HR_RiverSP_2.0
or
&collection_name=SWOT_L2_HR_RiverSP_reach_2.0
and both would be valid. We would need to also check the feature_type parameter to verify which table to query in the case where they just specify the parent collection.