Merge pull request #11854 from IQSS/11852-notifs-api-pagination-unread

Implements pagination and unread-only filter options to notifications/all endpoint

Author: sekmiller

doc/release-notes/11852-notifications-api-pagination-and-only-unread.md

@@ -0,0 +1,72 @@
+## Notifications API Update
+
+**Endpoint:** `notifications/all`
+
+The user notifications endpoint has been enhanced with new optional query parameters to allow for more specific and
+efficient data retrieval.
+
+**1. Filter by Unread Status**
+
+You can now fetch only unread notifications by using the `onlyUnread` boolean parameter.
+
+* **`onlyUnread`**: (Optional, boolean) When set to `true`, the API will only return notifications that the user has not
+  yet marked as read.
+
+**Example:**
+
+```bash
+curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/notifications/all?onlyUnread=true"
+```
+
+**2. Pagination Support**
+
+Pagination is now supported through the limit and offset parameters, allowing you to retrieve notifications in smaller,
+manageable chunks.
+
+- **`limit`**: (Optional, integer) Specifies the maximum number of notifications to return.
+
+- **`offset`**: (Optional, integer) Specifies the number of notifications to skip before starting to return results.
+
+Example (Retrieve notifications 11 through 20):
+
+```bash
+curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/notifications/all?limit=10&offset=10"
+```
+
+**3 Breaking Change: API Response Format Updated**
+
+To support pagination and improve consistency across the API, the JSON response format for this endpoint has been
+changed. This is a breaking change and will require updates to any client code currently using this endpoint.
+
+**Old Format:**
+
+Previously, the response nested the notification list inside a notifications object within the data field.
+
+```
+{
+  "status": "OK",
+  "data": {
+    "notifications": [
+      / ... /
+    ]
+  }
+}
+```
+
+**New Format:**
+
+The response now includes a top-level totalCount field (required for pagination) and places the notification list
+directly in the data field. This flattens the structure and makes it consistent with other paginated endpoints.
+
+```
+{
+  "status": "OK",
+  "totalCount": 2,
+  "data": [
+    / ... /  
+  ]
+}
+```
+
+Related issue: #11852
+Related PR: #11854

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

@@ -13,13 +13,14 @@ v6.9
 - The POST /api/admin/makeDataCount/{id}/updateCitationsForDataset processing is now asynchronous and the response no longer includes the number of citations. The response can be OK if the request is queued or 503 if the queue is full (default queue size is 1000).
 - The way to set per-format size limits for tabular ingest has changed. JSON input is now used. See :ref:`:TabularIngestSizeLimit`.
 - In the past, the settings API would accept any key and value. This is no longer the case because validation has been added. See :ref:`settings_put_single`, for example.
+- For GET /api/notifications/all the JSON response has changed breaking the backward compatibility of the API.
 
 v6.8
 ----
 
 - For POST /api/files/{id}/metadata passing an empty string ("description":"")  or array ("categories":[]) will no longer be ignored. Empty fields will now clear out the values in the file's metadata. To ignore the fields simply do not include them in the JSON string.
 - For PUT /api/datasets/{id}/editMetadata the query parameter "sourceInternalVersionNumber" has been removed and replaced with "sourceLastUpdateTime" to verify that the data being edited hasn't been modified and isn't stale.
-- For GET /api/dataverses/$dataverse-alias/links the Json response has changed breaking the backward compatibility of the API.
+- For GET /api/dataverses/$dataverse-alias/links the JSON response has changed breaking the backward compatibility of the API.
 - For GET /api/admin/dataverse/{dataverse-alias}/storageDriver and /api/datasets/{identifier}/storageDriver the driver name is no longer returned in data.message. This value is now returned in data.name.
 - For PUT /api/dataverses/$dataverse-alias/inputLevels custom input levels that had been previously set will no longer be deleted. To delete input levels send an empty list (deletes all), then send the new/modified list.
 - For GET /api/externalTools and /api/externalTools/{id} the responses are now formatted as JSON (previously the toolParameters and allowedApiCalls were a JSON object and array (respectively) that were serialized as JSON strings) and any configured "requirements" are included.

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

@@ -6520,44 +6520,65 @@ The expected OK (200) response looks something like this:
 
   {
       "status": "OK",
-      "data": {
-          "notifications": [
-              {
-                  "id": 38,
-                  "type": "CREATEACC",
-                  "displayAsRead": true,
-                  "subjectText": "Root: Your account has been created",
-                  "messageText": "Hello, \nWelcome to...",
-                  "sentTimestamp": "2025-07-21T19:15:37Z"
-              }
+      "totalCount": 15,
+      "data": [
+        {
+            "id": 38,
+            "type": "CREATEACC",
+            "displayAsRead": true,
+            "subjectText": "Root: Your account has been created",
+            "messageText": "Hello, \nWelcome to...",
+            "sentTimestamp": "2025-07-21T19:15:37Z"
+        }
   ...
 
-This endpoint supports an optional query parameter ``inAppNotificationFormat`` which, if sent as ``true``, retrieves the fields needed to build the in-app notifications for the Notifications section of the Dataverse UI, omitting fields related to email notifications.
+This endpoint supports several optional query parameters to filter and paginate the results.
+
+The ``inAppNotificationFormat`` parameter, if sent as ``true``, retrieves the fields needed to build the in-app notifications for the Notifications section of the Dataverse UI, omitting fields related to email notifications.
 
 .. code-block:: bash
 
   curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/notifications/all?inAppNotificationFormat=true"
 
-The expected OK (200) response looks something like this:
+The ``onlyUnread`` parameter, if sent as ``true``, filters the results to include only notifications that have not been marked as read.
+
+.. code-block:: bash
+
+  curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/notifications/all?onlyUnread=true"
+
+The ``limit`` and ``offset`` parameters can be used for pagination. ``limit`` specifies the maximum number of notifications to return, and ``offset`` specifies the number of notifications to skip from the beginning of the list. For example, to retrieve notifications 11 through 15:
+
+To aid in pagination the JSON response also includes the total number of rows (totalCount) available.
+
+.. code-block:: bash
+
+  curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/notifications/all?limit=5&offset=10"
+
+All parameters can be combined. For instance, to get the first page of 10 unread notifications in the in-app format:
+
+.. code-block:: bash
+
+  curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/notifications/all?inAppNotificationFormat=true&onlyUnread=true&limit=1&offset=0"
+
+The expected OK (200) response for an in-app format request looks something like this:
 
 .. code-block:: text
 
   {
       "status": "OK",
-      "data": {
-          "notifications": [
-              {
-                  "id": 79,
-                  "type": "CREATEACC",
-                  "displayAsRead": false,
-                  "sentTimestamp": "2025-08-08T08:00:16Z",
-                  "installationBrandName": "Your Installation Name",
-                  "userGuidesBaseUrl": "https://guides.dataverse.org",
-                  "userGuidesVersion": "6.7.1",
-                  "userGuidesSectionPath": "user/index.html"
-              }
-          ]
-      }
+      "totalCount": 15,
+      "data": [
+        {
+            "id": 79,
+            "type": "CREATEACC",
+            "displayAsRead": false,
+            "sentTimestamp": "2025-08-08T08:00:16Z",
+            "installationBrandName": "Your Installation Name",
+            "userGuidesBaseUrl": "https://guides.dataverse.org",
+            "userGuidesVersion": "6.7.1",
+            "userGuidesSectionPath": "user/index.html"
+        }
+      ]
   }
   ...
 

src/main/java/edu/harvard/iq/dataverse/UserNotificationServiceBean.java

@@ -18,7 +18,6 @@
 import jakarta.ejb.Stateless;
 import jakarta.ejb.TransactionAttribute;
 import jakarta.ejb.TransactionAttributeType;
-import jakarta.inject.Inject;
 import jakarta.inject.Named;
 import jakarta.persistence.EntityManager;
 import jakarta.persistence.PersistenceContext;
@@ -44,11 +43,63 @@ public class UserNotificationServiceBean {
     SettingsServiceBean settingsService;
 
     public List<UserNotification> findByUser(Long userId) {
-        TypedQuery<UserNotification> query = em.createQuery("select un from UserNotification un where un.user.id =:userId order by un.sendDate desc", UserNotification.class);
+        return findByUser(userId, false, null, null);
+    }
+
+    /**
+     * Finds notifications for a user, with options for pagination and filtering by read status.
+     *
+     * @param userId The ID of the user.
+     * @param onlyUnread If true, returns only unread notifications. If false, returns all.
+     * @param limit The maximum number of notifications to return (for pagination). Can be null.
+     * @param offset The starting position for the results (for pagination). Can be null.
+     * @return A list of UserNotification objects, ordered by send date descending.
+     */
+    public List<UserNotification> findByUser(Long userId, boolean onlyUnread, Integer limit, Integer offset) {
+        TypedQuery<UserNotification> query = em.createQuery(
+                "select un from UserNotification un " +
+                        "where un.user.id = :userId and (:onlyUnread = false or un.readNotification = false) " +
+                        "order by un.sendDate desc",
+                UserNotification.class
+        );
+
         query.setParameter("userId", userId);
+        query.setParameter("onlyUnread", onlyUnread);
+
+        if (offset != null) {
+            query.setFirstResult(offset);
+        }
+        if (limit != null) {
+            query.setMaxResults(limit);
+        }
+
         return query.getResultList();
     }
-    
+
+    /**
+     * Finds the total count of notifications for a user, with an option to count only unread notifications.
+     *
+     * @param userId The ID of the user.
+     * @param onlyUnread If true, counts only unread notifications. If false, counts all notifications.
+     * @return The total count as a Long.
+     */
+    public Long findTotalCountByUser(Long userId, boolean onlyUnread) {
+        if (userId == null) {
+            return 0L;
+        }
+
+        TypedQuery<Long> query = em.createQuery(
+                "select count(un) from UserNotification un " +
+                        "where un.user.id = :userId and (:onlyUnread = false or un.readNotification = false)",
+                Long.class
+        );
+
+        query.setParameter("userId", userId);
+        query.setParameter("onlyUnread", onlyUnread);
+
+        return query.getSingleResult();
+    }
+
     public List<UserNotification> findByRequestor(Long userId) {
         TypedQuery<UserNotification> query = em.createQuery("select un from UserNotification un where un.requestor.id =:userId order by un.sendDate desc", UserNotification.class);
         query.setParameter("userId", userId);

src/main/java/edu/harvard/iq/dataverse/api/Notifications.java

@@ -27,11 +27,16 @@ public class Notifications extends AbstractApiBean {
     @GET
     @AuthRequired
     @Path("/all")
-    public Response getAllNotificationsForUser(@Context ContainerRequestContext crc, @QueryParam("inAppNotificationFormat") boolean inAppNotificationFormat) {
+    public Response getAllNotificationsForUser(@Context ContainerRequestContext crc,
+                                               @QueryParam("onlyUnread") boolean onlyUnread,
+                                               @QueryParam("inAppNotificationFormat") boolean inAppNotificationFormat,
+                                               @QueryParam("limit") Integer limit,
+                                               @QueryParam("offset") Integer offset) {
         try {
             AuthenticatedUser authenticatedUser = getRequestAuthenticatedUserOrDie(crc);
-            List<UserNotification> userNotifications = userNotificationSvc.findByUser(authenticatedUser.getId());
-            return ok(Json.createObjectBuilder().add("notifications", json(userNotifications, authenticatedUser, inAppNotificationFormat)));
+            List<UserNotification> userNotifications = userNotificationSvc.findByUser(authenticatedUser.getId(), onlyUnread, limit, offset);
+            long userNotificationTotalCount = userNotificationSvc.findTotalCountByUser(authenticatedUser.getId(), onlyUnread);
+            return ok(json(userNotifications, authenticatedUser, inAppNotificationFormat), userNotificationTotalCount);
         } catch (WrappedResponse wr) {
             return wr.getResponse();
         }