task: allow request parameters to be specified for API calls

jwilkinson87 · jwilkinson87 · commit 86fc763f337b · 2025-02-05T13:21:47.000Z
diff --git a/src/main/kotlin/com/ctrlhub/core/assets/vehicles/VehicleCategoriesRouter.kt b/src/main/kotlin/com/ctrlhub/core/assets/vehicles/VehicleCategoriesRouter.kt
@@ -5,6 +5,7 @@ import com.ctrlhub.core.api.ApiClientException
 import com.ctrlhub.core.api.ApiException
 import com.ctrlhub.core.assets.vehicles.response.VehicleCategory
 import com.ctrlhub.core.router.Router
+import com.ctrlhub.core.router.request.RequestParameters
 import com.github.jasminb.jsonapi.ResourceConverter
 import com.github.jasminb.jsonapi.SerializationFeature
 import io.ktor.client.HttpClient
@@ -14,9 +15,16 @@ import io.ktor.client.plugins.ClientRequestException
 class VehicleCategoriesRouter(httpClient: HttpClient) : Router(httpClient, requiresAuthentication = true) {
     private val endpoint = "${Config.apiBaseUrl}/v3/assets/vehicles/categories"
 
-    suspend fun all(): List<VehicleCategory> {
+    /**
+     * Retrieve all vehicle categories
+     *
+     * @param requestParameters RequestParameters An instance of RequestParameters, capturing sorting, filtering and pagination based request params
+     *
+     * @return A list of vehicle categories
+     */
+    suspend fun all(requestParameters: RequestParameters = RequestParameters()): List<VehicleCategory> {
         return try {
-            val rawResponse = performGet(endpoint)
+            val rawResponse = performGet(endpoint, requestParameters.toMap())
             val resourceConverter = ResourceConverter(VehicleCategory::class.java).apply {
                 enableSerializationOption(SerializationFeature.INCLUDE_RELATIONSHIP_ATTRIBUTES)
             }
diff --git a/src/main/kotlin/com/ctrlhub/core/assets/vehicles/VehicleManufacturersRouter.kt b/src/main/kotlin/com/ctrlhub/core/assets/vehicles/VehicleManufacturersRouter.kt
@@ -7,6 +7,7 @@ import com.ctrlhub.core.assets.vehicles.response.VehicleManufacturer
 import com.ctrlhub.core.assets.vehicles.response.VehicleModel
 import com.ctrlhub.core.router.Router
 import com.ctrlhub.core.router.request.JsonApiIncludes
+import com.ctrlhub.core.router.request.RequestParameters
 import com.github.jasminb.jsonapi.ResourceConverter
 import com.github.jasminb.jsonapi.SerializationFeature
 import io.ktor.client.HttpClient
@@ -27,9 +28,16 @@ enum class VehicleManufacturerIncludes(val value: String) : JsonApiIncludes {
 class VehicleManufacturersRouter(httpClient: HttpClient) : Router(httpClient, requiresAuthentication = true) {
     private val endpoint: String = "${Config.apiBaseUrl}/v3/assets/vehicles/manufacturers"
 
-    suspend fun all(): List<VehicleManufacturer> {
+    /**
+     * Retrieve all vehicle manufacturers
+     *
+     * @param requestParameters RequestParameters An instance of RequestParameters, capturing sorting, and filtering based request params
+     *
+     * @return A list of vehicle manufacturers
+     */
+    suspend fun all(requestParameters: RequestParameters = RequestParameters()): List<VehicleManufacturer> {
         return try {
-            val rawResponse = performGet(endpoint)
+            val rawResponse = performGet(endpoint, requestParameters.toMap())
             val resourceConverter = ResourceConverter(VehicleManufacturer::class.java).apply {
                 enableSerializationOption(SerializationFeature.INCLUDE_RELATIONSHIP_ATTRIBUTES)
             }
@@ -47,11 +55,9 @@ class VehicleManufacturersRouter(httpClient: HttpClient) : Router(httpClient, re
         }
     }
 
-    suspend fun models(manufacturerId: String, vararg includes: VehicleManufacturerIncludes = emptyArray()): List<VehicleModel> {
+    suspend fun models(manufacturerId: String, requestParameters: RequestParameters = RequestParameters()): List<VehicleModel> {
         return try {
-            val includesStr = buildIncludesQueryString(*includes)
-
-            val rawResponse = performGet("$endpoint/$manufacturerId/models" + (if (includesStr.isNotEmpty()) "?$includesStr" else ""))
+            val rawResponse = performGet("$endpoint/$manufacturerId/models", requestParameters.toMap())
             val resourceConverter = ResourceConverter(VehicleModel::class.java).apply {
                 enableSerializationOption(SerializationFeature.INCLUDE_RELATIONSHIP_ATTRIBUTES)
             }
diff --git a/src/main/kotlin/com/ctrlhub/core/assets/vehicles/VehiclesRouter.kt b/src/main/kotlin/com/ctrlhub/core/assets/vehicles/VehiclesRouter.kt
@@ -7,6 +7,7 @@ import com.ctrlhub.core.assets.vehicles.response.Vehicle
 import com.ctrlhub.core.http.KtorClientFactory
 import com.ctrlhub.core.router.Router
 import com.ctrlhub.core.router.request.JsonApiIncludes
+import com.ctrlhub.core.router.request.RequestParameters
 import com.github.jasminb.jsonapi.ResourceConverter
 import com.github.jasminb.jsonapi.SerializationFeature
 import io.ktor.client.*
@@ -41,14 +42,17 @@ class VehiclesRouter(httpClient: HttpClient) : Router(httpClient, requiresAuthen
      * Request all vehicles
      *
      * @param organisationId String The organisation ID to retrieve all vehicles for
-     * @param includes A variable list of any includes, to return in the response. For example, VehicleIncludes.Specification will provide additional Specification attributes
+     * @param requestParameters RequestParameters An instance of RequestParameters, capturing sorting, filtering and pagination based request params
      *
      * @return A list of all vehicles
      */
-    suspend fun all(organisationId: String, vararg includes: VehicleIncludes = emptyArray()): List<Vehicle> {
+    suspend fun all(
+        organisationId: String,
+        requestParameters: RequestParameters = RequestParameters()
+    ): List<Vehicle> {
         return try {
-            val includesQuery = buildIncludesQueryString(*includes)
-            val rawResponse = performGet("/v3/orgs/$organisationId/assets/vehicles" + (if (includesQuery.isNotEmpty()) "?$includesQuery" else ""))
+            val rawResponse =
+                performGet("/v3/orgs/$organisationId/assets/vehicles", requestParameters.toMap())
             val resourceConverter = ResourceConverter(Vehicle::class.java).apply {
                 enableSerializationOption(SerializationFeature.INCLUDE_RELATIONSHIP_ATTRIBUTES)
             }
diff --git a/src/main/kotlin/com/ctrlhub/core/governance/OrganisationsRouter.kt b/src/main/kotlin/com/ctrlhub/core/governance/OrganisationsRouter.kt
@@ -7,6 +7,7 @@ import com.ctrlhub.core.api.ApiException
 import com.ctrlhub.core.governance.response.Organisation
 import com.ctrlhub.core.http.KtorClientFactory
 import com.ctrlhub.core.router.Router
+import com.ctrlhub.core.router.request.RequestParameters
 import com.github.jasminb.jsonapi.ResourceConverter
 import io.ktor.client.HttpClient
 import io.ktor.client.call.body
@@ -18,9 +19,9 @@ import io.ktor.client.plugins.ClientRequestException
 class OrganisationsRouter(httpClient: HttpClient) : Router(httpClient, requiresAuthentication = true) {
     private val endpoint = "${Config.apiBaseUrl}/v3/orgs"
 
-    suspend fun all(): List<Organisation> {
+    suspend fun all(requestParameters: RequestParameters = RequestParameters()): List<Organisation> {
         return try {
-            val rawResponse = performGet(endpoint)
+            val rawResponse = performGet(endpoint, requestParameters.toMap())
             val resourceConverter = ResourceConverter(Organisation::class.java)
             val jsonApiResponse = resourceConverter.readDocumentCollection<Organisation>(
                 (rawResponse.body<ByteArray>()),
diff --git a/src/main/kotlin/com/ctrlhub/core/router/Router.kt b/src/main/kotlin/com/ctrlhub/core/router/Router.kt
@@ -20,10 +20,10 @@ abstract class Router(val httpClient: HttpClient, val requiresAuthentication: Bo
         if (includes.isEmpty()) {
             return ""
         }
-        return "include=" + includes.joinToString(",") { it.value().lowercase() }
+        return includes.joinToString(",") { it.value().lowercase() }
     }
 
-    protected suspend fun performGet(endpoint: String): HttpResponse {
+    protected suspend fun performGet(endpoint: String, queryString: Map<String, String> = emptyMap()): HttpResponse {
         if (requiresAuthentication && sessionToken.isNullOrEmpty()) {
             throw MissingSessionTokenException()
         }
@@ -32,6 +32,9 @@ abstract class Router(val httpClient: HttpClient, val requiresAuthentication: Bo
             if (requiresAuthentication && !sessionToken.isNullOrEmpty()) headers {
                 header("X-Session-Token", sessionToken!!)
             }
+            url {
+                queryString.forEach { key, value -> parameters.append(key, value) }
+            }
         }
     }
 
diff --git a/src/main/kotlin/com/ctrlhub/core/router/request/RequestParameters.kt b/src/main/kotlin/com/ctrlhub/core/router/request/RequestParameters.kt
@@ -0,0 +1,35 @@
+package com.ctrlhub.core.router.request
+
+data class FilterOption(
+    val field: String,
+    val value: String
+)
+
+/**
+ * A class that represents request parameters that can be specified
+ * as part of an API request
+ */
+data class RequestParameters(
+    val filterOptions: List<FilterOption> = emptyList(),
+    val includes: List<JsonApiIncludes> = emptyList()
+) {
+    fun toMap(): Map<String, String> {
+        val queryParams = mutableMapOf<String, String>()
+
+        if (includes.isNotEmpty()) {
+            queryParams.put("include", buildIncludesQueryString(includes))
+        }
+
+        filterOptions.forEach { queryParams.put("filter[${it.field}]", it.value) }
+
+        return queryParams
+    }
+
+    private fun buildIncludesQueryString(includes: List<JsonApiIncludes>): String {
+        if (includes.isEmpty()) {
+            return ""
+        }
+
+        return includes.joinToString(",") { it.value().lowercase() }
+    }
+}
diff --git a/src/test/kotlin/com/ctrlhub/core/assets/vehicles/VehiclesRouterTest.kt b/src/test/kotlin/com/ctrlhub/core/assets/vehicles/VehiclesRouterTest.kt
@@ -2,6 +2,7 @@ package com.ctrlhub.core.assets.vehicles
 
 import com.ctrlhub.core.assets.vehicles.response.Vehicle
 import com.ctrlhub.core.configureForTest
+import com.ctrlhub.core.router.request.RequestParameters
 import io.ktor.client.HttpClient
 import io.ktor.client.engine.mock.MockEngine
 import io.ktor.client.engine.mock.respond
@@ -56,7 +57,10 @@ class VehiclesRouterTest {
         vehiclesRouter.sessionToken = "sess-123"
 
         runBlocking {
-            val response = vehiclesRouter.all(organisationId = "123", VehicleIncludes.SpecificationModel)
+            val response = vehiclesRouter.all(organisationId = "123", RequestParameters(
+                includes = listOf(VehicleIncludes.SpecificationModel)
+            ))
+
             assertIs<List<Vehicle>>(response)
             val first = response[0]
             assertNotNull(first.specification?.model)

Original file line number	Diff line number	Diff line change
`@@ -20,10 +20,10 @@ abstract class Router(val httpClient: HttpClient, val requiresAuthentication: Bo`
`20`	`20`	`if (includes.isEmpty()) {`
`21`	`21`	`return ""`
`22`	`22`	`}`
`23`		`- return "include=" + includes.joinToString(",") { it.value().lowercase() }`
	`23`	`+ return includes.joinToString(",") { it.value().lowercase() }`
`24`	`24`	`}`
`25`	`25`
`26`		`- protected suspend fun performGet(endpoint: String): HttpResponse {`
	`26`	`+ protected suspend fun performGet(endpoint: String, queryString: Map<String, String> = emptyMap()): HttpResponse {`
`27`	`27`	`if (requiresAuthentication && sessionToken.isNullOrEmpty()) {`
`28`	`28`	`throw MissingSessionTokenException()`
`29`	`29`	`}`
`@@ -32,6 +32,9 @@ abstract class Router(val httpClient: HttpClient, val requiresAuthentication: Bo`
`32`	`32`	`if (requiresAuthentication && !sessionToken.isNullOrEmpty()) headers {`
`33`	`33`	`header("X-Session-Token", sessionToken!!)`
`34`	`34`	`}`
	`35`	`+ url {`
	`36`	`+ queryString.forEach { key, value -> parameters.append(key, value) }`
	`37`	`+ }`
`35`	`38`	`}`
`36`	`39`	`}`
`37`	`40`