docs: add release note and API docs for #11639

Author: poikilotherm

doc/release-notes/11639-db-opts-idempotency.md

@@ -0,0 +1,21 @@
+## Database Settings Cleanup
+
+With this release, we remove some legacy specialties around Database Settings and provide better Admin API endpoints for them.
+
+Most important changes:
+
+1. Setting `BuiltinUsers.KEY` was renamed to `:BuiltinUsersKey`, aligned with our general naming pattern for options.
+2. Setting `:TabularIngestSizeLimit` no longer uses suffixes for formats and becomes a JSON-based setting instead.
+3. If set, both settings will be migrated to their new form automatically for you (Flyway migration).
+4. You can no longer (accidentally) create or use arbitrary setting names or languages.
+   All Admin API endpoints for settings now validate setting names and languages for existence and compliance.
+
+As an administrator of a Dataverse instance, you can now make use of enhanced Bulk Operations on the Settings Admin API:
+
+1. Retrieving all settings as JSON via `GET /api/admin/settings` supports localized options now, too.
+2. You can replace all existing settings in an idempotent way sending JSON to `PUT /api/admin/settings`.
+   This will create, update and remove settings as necessary in one atomic operation.  
+   The new endpoint is especially useful to admins using GitOps or other automations.
+   It allows control over all Database Settings from a single source without risking an undefined state.
+
+Note: Despite the validation of setting names and languages, the content of any database setting is still not being validated when using the Settings Admin API!

doc/sphinx-guides/source/api/native-api.rst

@@ -6530,7 +6530,11 @@ If the PID is not managed by Dataverse, this call will report if the PID is reco
 Admin
 -----
 
-This is the administrative part of the API. For security reasons, it is absolutely essential that you block it before allowing public access to a Dataverse installation. Blocking can be done using settings. See the ``post-install-api-block.sh`` script in the ``scripts/api`` folder for details. See :ref:`blocking-api-endpoints` in Securing Your Installation section of the Configuration page of the Installation Guide.
+This is the administrative part of the API.
+For security reasons, it is absolutely essential that you block it before allowing public access to a Dataverse installation.
+Blocking can be done using settings.
+See the ``post-install-api-block.sh`` script in the ``scripts/api`` folder for details.
+See :ref:`blocking-api-endpoints` in Securing Your Installation section of the Configuration page of the Installation Guide.
 
 List All Database Settings
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -6539,27 +6543,51 @@ List all settings::
 
   GET http://$SERVER/api/admin/settings
 
-Configure Database Setting
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _settings_put_bulk:
+
+Configure All Database Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Replace all settings in a single idempotent and atomic operation::
+
+  PUT http://$SERVER/api/admin/settings
+
+See JSON ``data`` object in output of ``GET /api/admin/settings`` for the JSON input structure for this endpoint.
+The :doc:`../installation/config` page of the Installation Guide has a :ref:`complete list of all the available settings <database-settings>`.
+
+Configure Single Database Setting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Sets setting ``name`` to the body of the request::
 
   PUT http://$SERVER/api/admin/settings/$name
 
+Sets a localized setting ``name`` for locale/language ``lang`` to the body of the request::
+
+  PUT http://$SERVER/api/admin/settings/$name/lang/$lang
+
 Get Single Database Setting
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Get the setting under ``name``::
 
   GET http://$SERVER/api/admin/settings/$name
 
-Delete Database Setting
-~~~~~~~~~~~~~~~~~~~~~~~
+Gets a localized setting under ``name`` for locale/language ``lang``::
+
+  GET http://$SERVER/api/admin/settings/$name/lang/$lang
+
+Delete Single Database Setting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Delete the setting under ``name``::
 
   DELETE http://$SERVER/api/admin/settings/$name
 
+Delete a localized setting under ``name`` for locale/language ``lang``::
+
+  DELETE http://$SERVER/api/admin/settings/$name/lang/$lang
+
 .. _list-all-feature-flags:
 
 List All Feature Flags

doc/sphinx-guides/source/installation/config.rst

@@ -3824,6 +3824,8 @@ The most commonly used configuration options are listed first.
 
 The pattern you will observe in curl examples below is that an HTTP ``PUT`` is used to add or modify a setting. If you perform an HTTP ``GET`` (the default when using curl), the output will contain the value of the setting, if it has been set. You can also do a ``GET`` of all settings with ``curl http://localhost:8080/api/admin/settings`` which you may want to pretty-print by piping the output through a tool such as jq by appending ``| jq .``. If you want to remove a setting, use an HTTP ``DELETE`` such as ``curl -X DELETE http://localhost:8080/api/admin/settings/:GuidesBaseUrl`` .
 
+For your convenience, there is also an Admin API endpoint to :ref:`bulk manage database settings in an atomic, idempotent fashion <settings_put_bulk>`.
+
 .. _:BlockedApiPolicy:
 
 :BlockedApiPolicy (Deprecated)