NOTICE of future breaking changes [and workarounds]

[MikeNeilson]

What's going on?

We've been trying to get users to use our newer formats generally calls application/json;version=2 and the same for XML.
Unfortunately due to not wanting to break backwards comp ability the older formats that were generated in a way that is difficult to update were returned by default; especially when queries with browser outside of the swagger-ui.

This is causing confusion and problems with adoption.

The 3-month plan

• application/json will be the default when */* is presented in the accept adder
• application/json, application/xml will always point to the most recent version of the datatype
• data type versions, until deprecated, will be accessible by the version string.

The by-year-end plan (2024)

• The tab and csv formats will be dropped
• The version=1 formats (the current defaults with many nested elements) will be dropped (we don't do this until Nov/December to give more time to transition.)

The summary

Thus:

• application/json -> application/json;version=<latest> (or as in the Basins endpoint application/vnd.named+pg+json)
• application/json;version=2 -> itself
• application/json;version=1 -> the current (as of writing) formats

And same for XML.
We'll probably start using proper vendor prefixes (e.g. application/vnd.json...), at least for newer formats if any.

The default is to help newer users to not get confused. It is recommended to ALWAYS specify the Accept header for the given format you want so avoid random breakage.

This is in other documentation but the following will happen when a given data object version is deprecated:
a header will be included in the response:

• CWMS-Data-Format-Deprecated: <date of removal as ISO8601> <explination if any>

If practical, automated scripts should look for that header and inform maintainers of the script.
Barring any freakish security issues, the format will remain for at least 1 year.

Tracking of changes:

• Add versioned mime type for original formats #486
• Add deprecated Header to tab and CSV formats #484
• Switch processing of default accept header and simple names to newest format by default #485

[ktarbet]

in the summary does this line:

application/json -> application/json;version=2 (or as in the Basins endpoint application/vnd.named+pg+json)

mean:

application/json -> application/json;version=<latest> (or as in the Basins endpoint application/vnd.named+pg+json)

Or is the latest only used in the three month plan?

[MikeNeilson]

Oh, that's a good point I'll update the summary as "" clearer to the final intent.