Update decision records to rst.

MikeNeilson · MikeNeilson · commit 2dada8b4e769 · 2025-08-04T14:48:17.000Z
diff --git a/docs/source/data/index.rst b/docs/source/data/index.rst
@@ -0,0 +1,12 @@
+####
+Data
+####
+
+
+.. toctree:
+    :maxdepth: 1
+    :caption: Data
+
+
+    Location Levels <./location-levels.rst>
+    Time Series <./timeseries.rst>
diff --git a/docs/source/decisions/0001-api-versioning.rst b/docs/source/decisions/0001-api-versioning.rst
@@ -1,12 +1,17 @@
-# API Versioning and Reporting
+############################
+API Versioning and Reporting
+############################
 
-## Summary
+Summary
+=======
 
 API should provide a reason version and list/matrix of capabilities for a given instance of CDA
 
-## Opinions
+Opinions
+========
 
-### Opinion 1 Calendar versioning
+Opinion 1 Calendar versioning
+-----------------------------
 
 @MikeNeilson
 
@@ -22,23 +27,27 @@ With Calendar Versioning automation tools can just pick the current date when ap
 perhaps by merged into a particular branch.
 
 
-### Opinion 2 Users
+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
+Decision Status
+===============
 
 accepted
 
 1. Provide endpoint to retrieve current API version.
 2. Likely include capability list or matrix.
 
-## References
+References
+==========
 
 
-## Related decisions
+Related decisions
+=================
 
 - data-versioning
diff --git a/docs/source/decisions/0002-data-versioning.rst b/docs/source/decisions/0002-data-versioning.rst
@@ -1,12 +1,17 @@
-# Data Types use Calendar Versioning
+##################################
+Data Types use Calendar Versioning
+##################################
 
-## Summary
+Summary
+=======
 
 Instead of versioning the entire API, though the API has a version, we version the data types.
 
-## Opinions
+Opinions
+========
 
-### Opinion 1
+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
 
@@ -23,9 +28,10 @@ The header, Accept, informs the API what format, or formats, we are willing to a
 
 
 
-## Decision Status
+Decision Status
+---------------
 
-proposed
+partial acceptance
 
 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
 
@@ -40,11 +46,13 @@ Version format is `YYYY-MM-DD`
 
 [comment:] <> (Status: request for comments | proposed | accepted | rejected | deprecated | superseded)
 
-## References
+References
+==========
 
 I have several, I will dig them up likely next week
 
-## Notes
+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
diff --git a/docs/source/decisions/0003-searchability-and-catalogs.rst b/docs/source/decisions/0003-searchability-and-catalogs.rst
@@ -1,13 +1,18 @@
-# Data should be readily searchable
+#################################
+Data should be readily searchable
+#################################
 
-## Summary
+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
+Opinions
+========
 
-### Opinion 1
+Opinion 1
+---------
 
 Summary: Each data time should support it's own /catalog end point.
 
@@ -22,7 +27,8 @@ 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
+Opinion 2
+---------
 
 Summary: Each datatype under "catalog" should be a full path"
 
@@ -33,10 +39,12 @@ 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
+Decision Status
+===============
 
 proposed
 
 [comment:] <> (Status: request for comments | proposed | accepted | rejected | deprecated | superseded)
 
-## References
+References
+==========
diff --git a/docs/source/decisions/0004-versioning.rst b/docs/source/decisions/0004-versioning.rst
@@ -0,0 +1,61 @@
+########################
+CWMS Data Api Versioning
+########################
+
+
+Summary
+=======
+
+Maintaining backwards compatibilty while improving future difficulty has proven sufficiently difficulty that change
+is required.
+
+The API as a whole will retain the calendar based versioning for formal releases.
+Data *SHOULD* be versioned, if appropriate/needed, with otherwise backwards compatible changes to query parameters.
+Endpoints will be places under a new "api version" for backwards incompatible or confusing parameter changes.
+
+e.g.
+
+`https://host/cwms-data/locations`
+
+can become
+
+`https://host/cwms-data/v2/locations`
+
+As additional endpoints require such a change they should be added to an existing increased version.
+
+Example:
+
+given above and a v1 `timeseries` and yet another `locations` improvements
+
+.. code-block:
+
+    #new time series becomes
+    cwms-data/v2/timeseries
+    # the new location becomes
+    cwms-data/v3/locations
+
+.. NOTE:
+
+    Or is that confusing and we should just allows add a new endpoint to the highest endpoint version?
+
+Opinions
+========
+
+Opinion 1
+---------
+
+Summary: Current scheme is not working
+
+Author MikeNeilson, on behalf of others
+
+We have failed to properly handle existing usages while attempting to improve the overall design of the api
+and have been breaking various downstream usages due to the confusion. Allowing the endpoints to be versioned allows
+an easier time keeping existing behavior while at allowing more drastic improvements in usages to happen.
+
+Decision Status
+===============
+
+[comment:] <> (Status: request for comments | proposed | accepted | rejected | deprecated | superseded)
+
+References
+==========
diff --git a/docs/source/decisions/adr-template.rst b/docs/source/decisions/adr-template.rst
@@ -1,19 +1,27 @@
-# Title
+#####
+Title
+#####
 
-## Summary
 
-## Opinions
+Summary
+=======
 
-### Opinion 1
+Opinions
+========
+
+Opinion 1
+---------
 
 Summary: 
 
 Author
 
 descriptive text
 
-## Decision Status
+Decision Status
+===============
 
 [comment:] <> (Status: request for comments | proposed | accepted | rejected | deprecated | superseded)
 
-## References
+References
+==========
diff --git a/docs/source/decisions/index.rst b/docs/source/decisions/index.rst
@@ -0,0 +1,23 @@
+################
+Design Decisions
+################
+
+
+Overview
+========
+
+
+Below are agree upon decision choices regarding the usage of the API.
+Please note that certain decisions may be agreed upon before implementation. 
+Whether or not a particular choice is implemented will be marked for each decision record.
+
+Some decisions may also be a proposal and marked appropriately.
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Decisions
+
+    Api Versioning <./0001-api-versioning.rst>
+    Data Versioning <./0002-data-versioning.rst>
+    Catalogs and Search <./0003-searchability-and-catalogs.rst>
+    Versioning <./0004-versioning.rst>
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -15,7 +15,9 @@ Welcome to CWMS Data API documentation!
    
    Overview <./introduction/overview.rst>
    Design <./introduction/design.rst>
+   Decision Records <./decisions/index.rst>
    Endpoints <./endpoints/index.rst>
    Glossary <./glossary.rst>
    FAQ <./faq.rst>
-   Client Libraries <./libraries.rst>
+   Client Libraries <./libraries.rst>
+   Data <./data/index.rst>
diff --git a/docs/source/libraries/java.rst b/docs/source/libraries/java.rst
@@ -0,0 +1,3 @@
+####
+Java
+####
