From 93e9a6d29192e02a1b2dba215d31fd15ae328e9b Mon Sep 17 00:00:00 2001 From: Mike Neilson Date: Fri, 22 Nov 2024 22:51:09 +0000 Subject: [PATCH] Creation of initial decision records. --- docs/decisions/0001-api-versioning.md | 44 +++++++++++++++ docs/decisions/0002-data-versioning.md | 55 +++++++++++++++++++ .../0003-searchability-and-catalogs.md | 42 ++++++++++++++ docs/decisions/adr-template.md | 19 +++++++ 4 files changed, 160 insertions(+) create mode 100644 docs/decisions/0001-api-versioning.md create mode 100644 docs/decisions/0002-data-versioning.md create mode 100644 docs/decisions/0003-searchability-and-catalogs.md create mode 100644 docs/decisions/adr-template.md diff --git a/docs/decisions/0001-api-versioning.md b/docs/decisions/0001-api-versioning.md new file mode 100644 index 000000000..1cbac020c --- /dev/null +++ b/docs/decisions/0001-api-versioning.md @@ -0,0 +1,44 @@ +# API Versioning and Reporting + +## Summary + +API should provide a reason version and list/matrix of capabilities for a given instance of CDA + +## Opinions + +### Opinion 1 Calendar versioning + +@MikeNeilson + +Summary: Calendar versioning is easier to support and automate with this API + +As the one whose has been making the "official" releases Semantic Version versioning has basically been useless. +We have been making so many feature additions that if I was doing it right we'd never have a minor version change between releases. +It's also caused me to, I think, release too slowly. + +While we can automate SemVer it is an additional step. + +With Calendar Versioning automation tools can just pick the current date when appropriately triggered, +perhaps by merged into a particular branch. + + +### Opinion 2 Users + +Summary: It has been asked more than once that a version be provided + +Having a version allows client to better respond to what's available instead of failing in obtuse ways. + + +## Decision Status + +accepted + +1. Provide endpoint to retrieve current API version. +2. Likely include capability list or matrix. + +## References + + +## Related decisions + +- data-versioning diff --git a/docs/decisions/0002-data-versioning.md b/docs/decisions/0002-data-versioning.md new file mode 100644 index 000000000..5a744a427 --- /dev/null +++ b/docs/decisions/0002-data-versioning.md @@ -0,0 +1,55 @@ +# Data Types use Calendar Versioning + +## Summary + +Instead of versioning the entire API, though the API has a version, we version the data types. + +## Opinions + +### Opinion 1 + +Summary: Versioning the API itself, at the level of the path, will lead to too many paths to manage and be awkward for the clients + +@MikeNeilson + +By versioning the data, and using the Content-Type and Accept headers and the full features of MIME types we appropriately +separate the concern of "what data we are retrieving/storing" from the presentation of data. + +e.g /timeseries/Alder Springs.Temp-Air.Inst.15Minutes.0.GOES-raw?begin=PT0&end=PT-1D&units=C, granted with a reasonable + exception to the units, defines *what* we want. + +The header, Accept, informs the API what format, or formats, we are willing to accept the data in. + + + + +## Decision Status + +proposed + +Data, by content-types, are versioned. In the past there was some severe confusion on this part and it was treated as anything new was "version=2" in the content-type. To allow this design but reduce confusion going forward + +1. The initial version of a data set *SHALL* be the date it was finalized (e.g. PR about to be merged.) +2. *IF* it is the first version of this data the plain content-type "e.g. application/json" will point to this data. +3. *IF* is it not the version version of this data, it will be discussed and announced when it becomes the new default data. +4. Downstream systems *SHOULD* use the specific version regardless of when implemented, and this behavior should be well documented. +5. If a given data set includes definitions of its shape within the type there should be sufficient documentation for downstream + developers to properly account for any changes over time. (See our TimeSeries type and discussions within #927). + +Version format is `YYYY-MM-DD` + +[comment:] <> (Status: request for comments | proposed | accepted | rejected | deprecated | superseded) + +## References + +I have several, I will dig them up likely next week + +## Notes + +The initial idea in CDA was that the first version of any data type was, we'll just stick with JSON for each of message, +"application/json;version=1" with "application/json" being the alias to the latest format version. However, this was not +correctly communicated and several brand new data transfer objects were created as ";version=2" under the impression that +this was the version for the new system. Attempting to use a simple number of this has clearly caused confusion in general. + +We also failed to create the initial alias system which caused even more confusion when users attempted to test things +directly in a browser instead of the provided swagger-ui. diff --git a/docs/decisions/0003-searchability-and-catalogs.md b/docs/decisions/0003-searchability-and-catalogs.md new file mode 100644 index 000000000..6e1d33992 --- /dev/null +++ b/docs/decisions/0003-searchability-and-catalogs.md @@ -0,0 +1,42 @@ +# Data should be readily searchable + +## Summary + +It's not just a good idea, it's technically the law. While CDA currently expose a fair amount of information to search +it's never entirely clear. + +## Opinions + +### Opinion 1 + +Summary: Each data time should support it's own /catalog end point. + +@MikeNeilson + +The original CDA has the say, `/timeseries` end point provide a catalog if no data is set. I created a /catalog end point +to attempt to consildate search query parameters. For TimeSeries and Locations this works reasonably well since there +is parity between the concepts. + +However, if we tried to add ratings into the mix, the list of query parameters grows, and it would rather difficult to +document which is for what or what changes for each. + +To make 'catalog' operations clear, we should create /catalog for each data type that provide for discoverability of that data. + +### Opinion 2 + +Summary: Each datatype under "catalog" should be a full path" + +@MikeNeilson + +If it makes sense to group all catalogs under catalog, perhaps for grouping in the SWAGGER-UI, making each catalog it's own +path under `/catalog` instead of the current path parameter is a better approach. + +We would maintain the grouping, but each catalog can have it's appropriate search criteria. + +## Decision Status + +proposed + +[comment:] <> (Status: request for comments | proposed | accepted | rejected | deprecated | superseded) + +## References diff --git a/docs/decisions/adr-template.md b/docs/decisions/adr-template.md new file mode 100644 index 000000000..6fad01441 --- /dev/null +++ b/docs/decisions/adr-template.md @@ -0,0 +1,19 @@ +# Title + +## Summary + +## Opinions + +### Opinion 1 + +Summary: + +Author + +descriptive text + +## Decision Status + +[comment:] <> (Status: request for comments | proposed | accepted | rejected | deprecated | superseded) + +## References