Fix nested message object in API responses

doc/release-notes/12096-fix-ok-message-nested-object.md

@@ -0,0 +1,27 @@
+### API Response Format Fix for `message` Field
+
+The `message` field in API responses from certain endpoints was incorrectly returned as a nested object (`{"message": {"message": "..."}}`) instead of a plain string (`{"message": "..."}`).
+
+This has been fixed. The following endpoints now return the `message` field as a string, consistent with all other API responses:
+
+- `POST /api/datasets/{id}/add` (when uploading duplicate files)
+- `PUT /api/admin/settings`
+- `PUT /api/dataverses/{id}`
+- `PUT /api/dataverses/{id}/inputLevels`
+- `POST /api/admin/savedsearches`
+- `PUT /api/harvest/clients/{nickName}`
+- `PUT /api/harvest/server/oaisets/{specname}`
+
+**Note:** If you have integrations that implemented workarounds for the nested `message` object, you may need to update your code to expect a plain string instead.
+If you need time to update your integrations, you can temporarily revert to the legacy behavior by setting this JVM option:
+
+```
+dataverse.legacy.api-response-message-style=true
+```
+
+This flag will be removed in a future version.
+
+**Note:** As of this version, there is also an experimental opt-in feature that will align API responses on about 230 more occassions.
+In these responses, the message is embedded into the "data" field as a nested object.
+If you want to test your integrations and clients, please enable the `dataverse.feature.unify-api-response-message-style` feature flag.
+In a future version of Dataverse, this now experimental style is going to become the supported default.

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

@@ -7,6 +7,19 @@ This API changelog is experimental and we would love feedback on its usefulness.
     :local:
     :depth: 1
 
+v6.10
+-----
+
+- Several API endpoints that return both a ``message`` and ``data`` field were incorrectly returning the message as a nested object (``{"message":{"message":"..."}}``).
+  This has been fixed so that the message is now a plain string (``{"message":"..."}``).
+  If you have integrations that depend on the old behavior, you can temporarily revert by setting ``dataverse.feature.api-message-field-legacy=true``.
+  This flag will be removed in a future version.
+  Affected endpoints: ``POST /api/datasets/{id}/add`` (duplicate file warning), ``PUT /api/admin/settings``, ``PUT /api/dataverses/{id}``, ``PUT /api/dataverses/{id}/inputLevels``, ``POST /api/admin/savedsearches``, ``PUT /api/harvest/clients/{nickName}``, ``PUT /api/harvest/server/oaisets/{specname}``.
+  See `#12096 <https://github.com/IQSS/dataverse/issues/12096>`_.
+- Most API endpoints that return a success notification but no actual data have it embedded into ``data``:  ``{"data":{"message":"..."}}``.
+  For now, this style will remain the supported default. In a future version of Dataverse the ``message`` will always be a separate top field: ``{"data":{},"message":"..."}``.
+  Integrators and client vendors are welcome to opt-in to the new style and test thoroughly by enabling :ref:`dataverse.feature.unify-api-response-message-style`.
+
 v6.9
 ----
 

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

@@ -3388,6 +3388,31 @@ Can also be set via any `supported MicroProfile Config API source`_, e.g. the en
    This setting will be ignored unless the :ref:`dataverse.api.blocked.policy` is set to ``unblock-key``.  Otherwise the deprecated :ref:`:BlockedApiKey` will be used
 
 
+.. _dataverse.legacy.api-response-message-style:
+
+dataverse.legacy.api-response-message-style
++++++++++++++++++++++++++++++++++++++++++++
+
+Opt-out of no longer nesting an object in the "message" field, carrying the actual notification in its "message" field.
+Enabling this will re-activate the legacy message style using ``{"message":{"message":"..."}}``, instead of the aligned format ``{"message": "..."}``.
+
+This option is provided as a temporary workaround for integrations that may have implemented
+workarounds for the buggy behavior. The following endpoints are affected:
+
+- ``POST /api/datasets/{id}/add`` (just the duplicate file warning)
+- ``PUT /api/admin/settings``
+- ``PUT /api/dataverses/{id}``
+- ``PUT /api/dataverses/{id}/inputLevels``
+- ``POST /api/admin/savedsearches``
+- ``PUT /api/harvest/clients/{nickName}``
+- ``PUT /api/harvest/server/oaisets/{specname}``
+
+Please update your integrations to expect the corrected message format and deactivate this setting.
+In a future version of Dataverse, the legacy format is expected to be removed completely.
+See also :ref:`dataverse.feature.unify-api-response-message-style`.
+
+Can also be set via any `supported MicroProfile Config API source`_, e.g. the environment variable ``DATAVERSE_LEGACY_API_RESPONSE_MESSAGE_STYLE``.
+
 .. _dataverse.ui.show-validity-label-when-published:
 
 dataverse.ui.show-validity-label-when-published
@@ -3933,6 +3958,19 @@ dataverse.feature.api-bearer-auth-use-oauth-user-on-id-match
 
 Allows the use of an OAuth user account (GitHub, Google, or ORCID) when an identity match is found during API bearer authentication. This feature enables automatic association of an incoming IdP identity with an existing OAuth user account, bypassing the need for additional user registration steps. This feature only works when the feature flag ``api-bearer-auth`` is also enabled. **Caution: Enabling this flag could result in impersonation risks if (and only if) used with a misconfigured IdP.**
 
+.. _dataverse.feature.unify-api-response-message-style:
+
+dataverse.feature.unify-api-response-message-style
+++++++++++++++++++++++++++++++++++++++++++++++++++
+
+When activated, the "message" in API responses will no longer be nested in the "data" field.
+For any response carrying a notification, these will be found within a top-level "message" field of the JSON returned.
+This affects about 230 endpoints and is likely to break existing integrations and clients.
+It is mandatory to test instance clients and integrations thoroughly and it is not recommended to be used in production.
+In a future Dataverse version, the (currently) experimental response message style will be made the only supported one.
+
+See also :ref:`dataverse.legacy.api-response-message-style`.
+
 .. _dataverse.feature.avoid-expensive-solr-join:
 
 dataverse.feature.avoid-expensive-solr-join