feat: support paginated responses on API endpoints

Author: jwilkinson87

.idea/misc.xml

@@ -0,0 +1,32 @@
+package com.ctrlhub.core.api.response
+
+data class PaginatedList<T>(
+    val data: List<T>,
+    val pagination: PaginationMeta
+)
+
+data class PaginationMeta(
+    val page: PageMeta,
+    val counts: CountsMeta,
+    val requested: RequestedMeta,
+    val offsets: OffsetsMeta
+)
+
+data class CountsMeta(
+    val resources: Int,
+    val pages: Int
+)
+
+data class PageMeta(
+    val currentPage: Int,
+)
+
+data class RequestedMeta(
+    val offset: Int?,
+    val limit: Int?
+)
+
+data class OffsetsMeta(
+    val previous: Int?,
+    val next: Int?
+)

src/main/kotlin/com/ctrlhub/core/api/response/Pagination.kt

@@ -1,6 +1,7 @@
 package com.ctrlhub.core.assets.equipment
 
 import com.ctrlhub.core.Api
+import com.ctrlhub.core.api.response.PaginatedList
 import com.ctrlhub.core.assets.equipment.resource.EquipmentItem
 import com.ctrlhub.core.router.Router
 import com.ctrlhub.core.router.request.FilterOption
@@ -25,9 +26,11 @@ enum class EquipmentIncludes(val value: String) : JsonApiIncludes {
 }
 
 class EquipmentRequestParameters(
+    offset: Int = 0,
+    limit: Int = 100,
     filterOptions: List<FilterOption> = emptyList(),
     includes: List<EquipmentIncludes> = emptyList()
-) : RequestParametersWithIncludes<EquipmentIncludes>(filterOptions, includes)
+) : RequestParametersWithIncludes<EquipmentIncludes>(offset, limit, filterOptions, includes)
 
 enum class EquipmentSort(val value: String) {
     Name("name");
@@ -46,8 +49,8 @@ class EquipmentRouter (httpClient: HttpClient) : Router(httpClient) {
     suspend fun all(
         organisationId: String,
         requestParameters: EquipmentRequestParameters = EquipmentRequestParameters()
-    ) : List<EquipmentItem> {
-        return fetchJsonApiResources(
+    ) : PaginatedList<EquipmentItem> {
+        return fetchPaginatedJsonApiResources(
             "/v3/orgs/$organisationId/assets/equipment",
             requestParameters.toMap()
         )

src/main/kotlin/com/ctrlhub/core/assets/equipment/EquipmentRouter.kt

@@ -21,9 +21,11 @@ enum class EquipmentExposureIncludes(val value: String) : JsonApiIncludes {
 }
 
 class EquipmentExposureRequestParameters(
+    offset: Int = 0,
+    limit: Int = 100,
     filterOptions: List<FilterOption> = emptyList(),
     includes: List<EquipmentExposureIncludes> = emptyList()
-) : RequestParametersWithIncludes<EquipmentExposureIncludes>(filterOptions, includes)
+) : RequestParametersWithIncludes<EquipmentExposureIncludes>(offset, limit, filterOptions, includes)
 
 /**
  * An equipment exposure router that deals with the exposures realm of the Ctrl Hub API

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

@@ -1,6 +1,7 @@
 package com.ctrlhub.core.assets.vehicles
 
 import com.ctrlhub.core.Api
+import com.ctrlhub.core.api.response.PaginatedList
 import com.ctrlhub.core.assets.vehicles.resource.VehicleCategory
 import com.ctrlhub.core.router.Router
 import com.ctrlhub.core.router.request.RequestParameters
@@ -19,8 +20,8 @@ class VehicleCategoriesRouter(httpClient: HttpClient) : Router(httpClient) {
      *
      * @return A list of vehicle categories
      */
-    suspend fun all(requestParameters: RequestParameters = RequestParameters()): List<VehicleCategory> {
-        return fetchJsonApiResources(endpoint, requestParameters.toMap())
+    suspend fun all(requestParameters: RequestParameters = RequestParameters()): PaginatedList<VehicleCategory> {
+        return fetchPaginatedJsonApiResources(endpoint, requestParameters.toMap())
     }
 }
 

src/main/kotlin/com/ctrlhub/core/assets/vehicles/VehicleCategoriesRouter.kt

@@ -1,5 +1,6 @@
 package com.ctrlhub.core.assets.vehicles
 
+import com.ctrlhub.core.api.response.PaginatedList
 import com.ctrlhub.core.assets.vehicles.resource.VehicleInspection
 import com.ctrlhub.core.router.Router
 import com.ctrlhub.core.router.request.RequestParameters
@@ -24,10 +25,10 @@ class VehicleInspectionsRouter(httpClient: HttpClient) : Router(httpClient) {
         organisationId: String,
         vehicleId: String,
         requestParameters: RequestParameters = RequestParameters()
-    ): List<VehicleInspection> {
+    ): PaginatedList<VehicleInspection> {
         val endpoint = "/v3/orgs/$organisationId/assets/vehicles/$vehicleId/inspections"
 
-        return fetchJsonApiResources(endpoint, requestParameters.toMap())
+        return fetchPaginatedJsonApiResources(endpoint, requestParameters.toMap())
     }
 
     /**

src/main/kotlin/com/ctrlhub/core/assets/vehicles/VehicleInspectionsRouter.kt

@@ -1,6 +1,7 @@
 package com.ctrlhub.core.assets.vehicles
 
 import com.ctrlhub.core.Api
+import com.ctrlhub.core.api.response.PaginatedList
 import com.ctrlhub.core.assets.vehicles.resource.VehicleManufacturer
 import com.ctrlhub.core.assets.vehicles.resource.VehicleModel
 import com.ctrlhub.core.router.Router
@@ -29,8 +30,8 @@ class VehicleManufacturersRouter(httpClient: HttpClient) : Router(httpClient) {
      *
      * @return A list of vehicle manufacturers
      */
-    suspend fun all(requestParameters: RequestParameters = RequestParameters()): List<VehicleManufacturer> {
-        return fetchJsonApiResources(endpoint, requestParameters.toMap())
+    suspend fun all(requestParameters: RequestParameters = RequestParameters()): PaginatedList<VehicleManufacturer> {
+        return fetchPaginatedJsonApiResources(endpoint, requestParameters.toMap())
     }
 
     suspend fun models(manufacturerId: String, requestParameters: RequestParameters = RequestParameters()): List<VehicleModel> {

src/main/kotlin/com/ctrlhub/core/assets/vehicles/VehicleManufacturersRouter.kt

@@ -1,6 +1,7 @@
 package com.ctrlhub.core.assets.vehicles
 
 import com.ctrlhub.core.Api
+import com.ctrlhub.core.api.response.PaginatedList
 import com.ctrlhub.core.assets.vehicles.resource.Vehicle
 import com.ctrlhub.core.iam.response.User
 import com.ctrlhub.core.router.Router
@@ -29,9 +30,11 @@ enum class VehicleIncludes(val value: String) : JsonApiIncludes {
 }
 
 class VehicleRequestParameters(
+    offset: Int = 0,
+    limit: Int = 100,
     filterOptions: List<FilterOption> = emptyList(),
     includes: List<VehicleIncludes> = emptyList()
-) : RequestParametersWithIncludes<VehicleIncludes>(filterOptions, includes)
+) : RequestParametersWithIncludes<VehicleIncludes>(offset, limit, filterOptions, includes)
 
 /**
  * A vehicles router that deals with the vehicles realm of the Ctrl Hub API
@@ -49,8 +52,8 @@ class VehiclesRouter(httpClient: HttpClient) : Router(httpClient) {
     suspend fun all(
         organisationId: String,
         requestParameters: VehicleRequestParameters = VehicleRequestParameters()
-    ): List<Vehicle> {
-        return fetchJsonApiResources(
+    ): PaginatedList<Vehicle> {
+        return fetchPaginatedJsonApiResources(
             "/v3/orgs/$organisationId/assets/vehicles",
             requestParameters.toMap(),
             User::class.java

src/main/kotlin/com/ctrlhub/core/assets/vehicles/VehiclesRouter.kt

@@ -1,13 +1,14 @@
 package com.ctrlhub.core.datacapture
 
 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 io.ktor.client.HttpClient
 
 class FormsRouter(httpClient: HttpClient) : Router(httpClient) {
-    suspend fun all(organisationId: String): List<Form> {
-        return fetchJsonApiResources("/v3/orgs/${organisationId}/data-capture/forms", emptyMap(), Form::class.java)
+    suspend fun all(organisationId: String): PaginatedList<Form> {
+        return fetchPaginatedJsonApiResources("/v3/orgs/${organisationId}/data-capture/forms", emptyMap(), Form::class.java)
     }
 
     suspend fun one(organisationId: String, formId: String): Form {

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

@@ -1,15 +1,13 @@
 package com.ctrlhub.core.governance
 
 import com.ctrlhub.core.Api
-import com.ctrlhub.core.Config
 import com.ctrlhub.core.api.ApiClientException
 import com.ctrlhub.core.api.ApiException
+import com.ctrlhub.core.api.response.PaginatedList
 import com.ctrlhub.core.governance.response.Organisation
 import com.ctrlhub.core.router.Router
 import com.ctrlhub.core.router.request.RequestParameters
-import com.github.jasminb.jsonapi.ResourceConverter
 import io.ktor.client.*
-import io.ktor.client.call.*
 import io.ktor.client.plugins.*
 
 /**
@@ -18,16 +16,9 @@ import io.ktor.client.plugins.*
 class OrganisationsRouter(httpClient: HttpClient) : Router(httpClient) {
     private val endpoint = "/v3/orgs"
 
-    suspend fun all(requestParameters: RequestParameters = RequestParameters()): List<Organisation> {
+    suspend fun all(requestParameters: RequestParameters = RequestParameters()): PaginatedList<Organisation> {
         return try {
-            val rawResponse = performGet(endpoint, requestParameters.toMap())
-            val resourceConverter = ResourceConverter(Organisation::class.java)
-            val jsonApiResponse = resourceConverter.readDocumentCollection<Organisation>(
-                (rawResponse.body<ByteArray>()),
-                Organisation::class.java
-            )
-
-            jsonApiResponse.get()!!
+            fetchPaginatedJsonApiResources(endpoint, requestParameters.toMap(), Organisation::class.java)
         } catch (e: ClientRequestException) {
             throw ApiClientException("all organisations GET request failed", e.response, e)
         } catch (e: Exception) {