Update the collections API docs for ID-based URLs and transition paths

[aaccensi]

Context

The Collections URL worked by defining the etengine session ids and the title (a link could be hand-crafted to show any scenarios under any heading). The current wish is to have the URL contain the collection id instead and then fetch the corresponding session ids with the my-etm API; yet keep the previous behaviour alive for compatibility with older links.

Implemented changes

• collections_app_url carries the collection's ID and locale only; the title and the scenario IDs are no longer part of it.
• Responses include scenarios, listing every scenario in the order it is shown and pairing each with the saved scenario it came from. It is read-only, so scenario_ids and saved_scenario_ids remain the way to change what a collection holds.
• interpolation_params.end_years comes from the collection's saved scenarios rather than from the collection's own end_year field, so the note describing it now says which of the two values comes from where. The transition path example shows a collection whose scenarios are all saved scenarios.
• Adds notes on who may read a collection, and on transition paths: they hold one saved scenario per end year, this endpoint does not interpolate, and a client setting interpolation must pass no more than one scenario per end year, all in a single area.

Related

This is part of a 3 PRs effort:

• my-etm: Address collections by id in the Collections app URL my-etm#308
• collections: Resolve collections by id, keeping the scenario-ids URLs working multi-year-charts#129
• documentation: Update the collections API docs for ID-based URLs and transition paths #368 [this one]

Checklist

• I have tested these changes
• I have updated documentation as needed
• I have tagged the relevant people for review

[louispt1]

I believedata/api/collections.js needs adjusting as well