feat: support paginated responses on API endpoints

Author: jwilkinson87

src/main/kotlin/com/ctrlhub/core/assets/equipment/exposures/EquipmentExposuresRouter.kt

@@ -1,5 +1,6 @@
 package com.ctrlhub.core.assets.equipment.exposures
 
+import com.ctrlhub.core.api.response.PaginatedList
 import com.ctrlhub.core.assets.equipment.EquipmentRouter
 import com.ctrlhub.core.assets.equipment.exposures.resource.EquipmentExposureResource
 import com.ctrlhub.core.assets.equipment.resource.EquipmentItem
@@ -45,8 +46,8 @@ class EquipmentExposuresRouter(httpClient: HttpClient) : Router(httpClient) {
         organisationId: String,
         equipmentId: String,
         requestParameters: EquipmentExposureRequestParameters = EquipmentExposureRequestParameters()
-    ): List<EquipmentExposureResource> {
-        return fetchJsonApiResources(
+    ): PaginatedList<EquipmentExposureResource> {
+        return fetchPaginatedJsonApiResources(
             "/v3/orgs/$organisationId/assets/equipment/$equipmentId/exposures",
             requestParameters.toMap()
         )

src/main/kotlin/com/ctrlhub/core/datacapture/FormsRouter.kt

@@ -4,11 +4,19 @@ import com.ctrlhub.core.Api
 import com.ctrlhub.core.api.response.PaginatedList
 import com.ctrlhub.core.datacapture.response.Form
 import com.ctrlhub.core.router.Router
+import com.ctrlhub.core.router.request.RequestParameters
 import io.ktor.client.HttpClient
 
 class FormsRouter(httpClient: HttpClient) : Router(httpClient) {
-    suspend fun all(organisationId: String): PaginatedList<Form> {
-        return fetchPaginatedJsonApiResources("/v3/orgs/${organisationId}/data-capture/forms", emptyMap(), Form::class.java)
+    suspend fun all(
+        organisationId: String,
+        requestParameters: RequestParameters = RequestParameters()
+    ): PaginatedList<Form> {
+        return fetchPaginatedJsonApiResources(
+            "/v3/orgs/${organisationId}/data-capture/forms",
+            requestParameters.toMap(),
+            Form::class.java
+        )
     }
 
     suspend fun one(organisationId: String, formId: String): Form {

src/main/kotlin/com/ctrlhub/core/governance/schemes/SchemesRouter.kt

@@ -1,6 +1,7 @@
 package com.ctrlhub.core.governance.schemes
 
 import com.ctrlhub.core.Api
+import com.ctrlhub.core.api.response.PaginatedList
 import com.ctrlhub.core.governance.schemes.response.Scheme
 import com.ctrlhub.core.governance.schemes.workorders.response.WorkOrder
 import com.ctrlhub.core.iam.response.User
@@ -36,8 +37,8 @@ class SchemesRouter(httpClient: HttpClient) : Router(httpClient) {
      *
      * @return A list of all schemes
      */
-    suspend fun all(organisationId: String, requestParameters: SchemeRequestParameters = SchemeRequestParameters()): List<Scheme> {
-        return fetchJsonApiResources("/v3/orgs/$organisationId/governance/schemes", requestParameters.toMap(), Scheme::class.java,
+    suspend fun all(organisationId: String, requestParameters: SchemeRequestParameters = SchemeRequestParameters()): PaginatedList<Scheme> {
+        return fetchPaginatedJsonApiResources("/v3/orgs/$organisationId/governance/schemes", requestParameters.toMap(), Scheme::class.java,
             WorkOrder::class.java, User::class.java)
     }
 

src/test/kotlin/com/ctrlhub/core/PaginatedRequestTest.kt

@@ -0,0 +1,27 @@
+package com.ctrlhub.core
+
+import com.ctrlhub.core.router.request.RequestParameters
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class PaginatedRequestTest {
+    @Test
+    fun `can set limit correctly in request`() {
+        val request = RequestParameters(
+            limit = 10
+        )
+
+        val queryParams = request.toMap()
+        assertEquals("10", queryParams["limit"])
+    }
+
+    @Test
+    fun `can set offset correctly in request`() {
+        val request = RequestParameters(
+            offset = 10
+        )
+
+        val queryParams = request.toMap()
+        assertEquals("10", queryParams["offset"])
+    }
+}

src/test/kotlin/com/ctrlhub/core/PaginatedResponseTest.kt

@@ -0,0 +1,40 @@
+package com.ctrlhub.core
+
+import com.ctrlhub.core.datacapture.FormsRouter
+import io.ktor.client.*
+import io.ktor.client.engine.mock.*
+import io.ktor.http.*
+import kotlinx.coroutines.runBlocking
+import java.nio.file.Files
+import java.nio.file.Paths
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class PaginatedResponseTest {
+    @Test
+    fun `can retrieve pagination meta correctly`() {
+        val jsonFilePath = Paths.get("src/test/resources/paginated-response.json")
+        val jsonContent = Files.readString(jsonFilePath)
+
+        val mockEngine = MockEngine { request ->
+            respond(
+                content = jsonContent,
+                status = HttpStatusCode.OK,
+                headers = headersOf(HttpHeaders.ContentType, "application/json")
+            )
+        }
+
+        val formsRouter = FormsRouter(httpClient = HttpClient(mockEngine).configureForTest())
+
+        runBlocking {
+            val response = formsRouter.all(organisationId = "123")
+            assertEquals(1, response.pagination.page.currentPage)
+            assertEquals(10, response.pagination.counts.resources)
+            assertEquals(5, response.pagination.counts.pages)
+            assertEquals(0, response.pagination.requested.offset)
+            assertEquals(100, response.pagination.requested.limit)
+            assertEquals(2, response.pagination.offsets.previous)
+            assertEquals(3, response.pagination.offsets.next)
+        }
+    }
+}

src/test/kotlin/com/ctrlhub/core/assets/equipment/exposures/EquipmentExposuresRouterTest.kt

@@ -1,5 +1,6 @@
 package com.ctrlhub.core.assets.equipment.exposures
 
+import com.ctrlhub.core.api.response.PaginatedList
 import com.ctrlhub.core.assets.equipment.exposures.resource.EquipmentExposureResource
 import com.ctrlhub.core.configureForTest
 import io.ktor.client.HttpClient
@@ -33,8 +34,8 @@ class EquipmentExposuresRouterTest {
 
         runBlocking {
             val response = exposuresRouter.all(organisationId = "000", equipmentId = "000")
-            assertIs<List<EquipmentExposureResource>>(response)
-            assertNotNull(response[0].id)
+            assertIs<PaginatedList<EquipmentExposureResource>>(response)
+            assertNotNull(response.data[0].id)
         }
     }
 

src/test/kotlin/com/ctrlhub/core/governance/schemes/SchemesRouterTest.kt

@@ -1,5 +1,6 @@
 package com.ctrlhub.core.governance.schemes
 
+import com.ctrlhub.core.api.response.PaginatedList
 import com.ctrlhub.core.configureForTest
 import com.ctrlhub.core.governance.schemes.response.Scheme
 import io.ktor.client.HttpClient
@@ -40,8 +41,8 @@ class SchemesRouterTest {
                 )
             ))
 
-            assertIs<List<Scheme>>(response)
-            assertNotNull(response[0].id)
+            assertIs<PaginatedList<Scheme>>(response)
+            assertNotNull(response.data[0].id)
         }
     }
 

src/test/resources/paginated-response.json

@@ -0,0 +1,71 @@
+{
+  "data": [
+    {
+      "id": "0c8ae6a0-5617-4205-b11d-9ae0e74e88b7",
+      "type": "forms",
+      "attributes": {
+        "description": "...",
+        "name": "Form 3",
+        "status": "active"
+      },
+      "relationships": {
+        "categories": {
+          "data": [
+            {
+              "id": "0ebac71d-bb15-4936-9b65-2d8089050997",
+              "type": "form-categories"
+            }
+          ]
+        },
+        "organisation": {
+          "data": {
+            "id": "bc7b2a6f-3b0c-4f4c-b63e-25dca7bc656e",
+            "type": "organisations"
+          }
+        },
+        "schemas": {
+          "data": []
+        }
+      },
+      "meta": {
+        "created_at": "2025-05-07T07:31:52.473Z",
+        "updated_at": "2025-05-12T11:49:20.536Z",
+        "counts": {
+          "schemas": 0,
+          "categories": 1
+        }
+      }
+    }
+  ],
+  "meta": {
+    "pagination": {
+      "current_page": 1,
+      "counts": {
+        "resources": 10,
+        "pages": 5
+      },
+      "requested": {
+        "offset": 0,
+        "limit": 100
+      },
+      "offsets": {
+        "previous": 2,
+        "next": 3
+      }
+    },
+    "features": {
+      "params": {
+        "include": {
+          "options": null
+        },
+        "sort": {
+          "default": "",
+          "options": null
+        }
+      }
+    }
+  },
+  "jsonapi": {
+    "version": "1.0"
+  }
+}