harmonize basemaps/mosaics api name and planet client name

[jreiberkyle]

Currently, the planet client uses planet mosaics to interact with the basemaps api. Maybe we can consider either changing the name of the client to basemaps or changing the name of the api (probably harder LOL)

[joferkington]

For whatever it's worth, the endpoint the python client is interacting with is called mosaics (api.planet.com/basemaps/v1/mosaics/), which is why the cli functionality is named mosaics. More generally, "mosaic" is the standard term for stitched together imagery, whereas "basemap" usually implies something different.

While I agree it would make sense to change it (especially now that there are functions under that heading that don't interact with the mosaics endpoint), please consider leaving an alias to mosaics at the very least. There actually is a lot of usage in the wild, and breaking changes are difficult for everyone.

[sarasafavi]

Yeah... this is a tricky one, due to the endpoint vs API name discrepancy, and the shift in how Planet refers to all of the above. In the documentation & guides related to the API we're handling it thusly: if a reference to the specific endpoint or API function is made, it's "mosaic"; otherwise a reference to the overall Planet product or the API itself is "basemaps".

So let's do this: in v2 going forward, the mosaics namespace in Python Client will be deprecated - but not removed, in order to support existing workflows. The new namespace will be basemaps, to keep with our API name -> CLI standard mapping.

When v2 is approaching release/beta announcements, we'll follow a decommissioning process for the mosaics namespace: deprecation notice in the decomm log, announcement of a target date or release version (if any) for when the command will be removed, and new documentation for the preferred basemaps usage.

[jreiberkyle]

Yep, I see your point @joferkington . @sarasafavi 's suggestion sounds like a good compromise to me!