task: refactor API to reduce duplication of code

Author: jwilkinson87

README.md

@@ -41,9 +41,11 @@ Config.environment = Environment.PRODUCTION // For production
 ```
 
 ### API object
-Interaction with the APIs is done via the `Api` class. This class exposes a number of factory methods for instantiating an `Api` object with either a default Ktor client, or a customised one.
+Interaction with the APIs is done via the `Api` singleton. The Api singleton provides access to a configured Ktor client for interaction with the Api. A session token can also be applied:
 
-```Api.create()```
+```kotlin
+Api.sessionToken = "valid_session_token"
+```
 
 ### Routers
 Routers are used to encapsulate specific areas of the API. For example, the `VehiclesRouter` takes care of all Vehicle API interactions. Routers are attached to the `Api` object via extension properties. 
@@ -52,27 +54,21 @@ Routers are used to encapsulate specific areas of the API. For example, the `Veh
 
 ```kotlin
 val api = Api.create()
-val response: List<Vehicle> = api.vehicles.all("your-session-token", "organisation-id", VehicleIncludes.SpecificationModel)
+val response: List<Vehicle> = api.vehicles.all("organisation-id", VehicleRequestParameters(
+    includes = listOf(
+        VehicleIncludes.Specification
+    )
+))
 ```
 
 ## Examples of Usage
 
 ```kotlin
 Config.environment = Environment.STAGING
-val api = Api.create()
-
-api.sessionToken = "sess-123"
-val response = api.vehicles.all("org-123", VehicleIncludes.SpecificationModel)
-println(response.size)
-```
-
-```kotlin
-Config.environment = Environment.STAGING
-val api = Api.create()
+Api.sessionToken = "" // Replace with an actual session token
 
-with(api.vehicles) {
-    sessionToken = "sess-123"
-    val response = all("org-123", VehicleIncludes.SpecificationModel)
+runBlocking {
+    val response = Api.vehicles.all("123")
     println(response.size)
 }
 ```

src/main/kotlin/com/ctrlhub/core/Api.kt

@@ -1,56 +1,15 @@
 package com.ctrlhub.core
 
 import com.ctrlhub.core.http.KtorClientFactory
-import io.ktor.client.HttpClient
-import io.ktor.client.plugins.UserAgent
-import io.ktor.client.plugins.contentnegotiation.ContentNegotiation
-import io.ktor.client.plugins.defaultRequest
-import io.ktor.http.HttpHeaders
-import io.ktor.serialization.kotlinx.json.json
-import io.ktor.util.appendIfNameAbsent
-import kotlinx.serialization.json.Json
+import io.ktor.client.*
 
 /**
- * The "facade" class through which interaction with the API occurs.
+ * The facade object through which interaction with the API occurs.
  */
-class Api private constructor(httpClient: HttpClient) {
-    companion object {
-        /**
-         * Creates a new Api instance with a default client
-         */
-        fun create(): Api {
-            val httpClient = KtorClientFactory.create()
-            return Api(configureHttpClient(httpClient, Config.apiBaseUrl))
-        }
+object Api {
+    var sessionToken: String? = null
 
-        /**
-         * Creates a new Api client, with a given HttpClient instance.
-         * Default config will be applied to this client
-         *
-         * @param httpClient HttpClient A ktor client instance
-         */
-        fun create(httpClient: HttpClient): Api {
-            return Api(httpClient)
-        }
-
-        private fun configureHttpClient(baseClient: HttpClient, baseUrl: String? = null): HttpClient {
-            return baseClient.config {
-                baseUrl?.let {
-                    defaultRequest {
-                        url(baseUrl)
-                    }
-                }
-                defaultRequest {
-                    headers.appendIfNameAbsent(HttpHeaders.ContentType, "application/json")
-                }
-                expectSuccess = true
-                install(ContentNegotiation) {
-                    json(Json { ignoreUnknownKeys = true })
-                }
-                install(UserAgent) {
-                    agent = Config.userAgent
-                }
-            }
-        }
+    val httpClient: HttpClient by lazy {
+        KtorClientFactory.create(sessionToken)
     }
 }

src/main/kotlin/com/ctrlhub/core/api/ApiException.kt

@@ -7,6 +7,11 @@ import io.ktor.client.statement.*
  */
 open class ApiException(message: String, e: Throwable) : Exception(message, e)
 
+/**
+ * Represents an authorized error that occurs when interacting with the API.
+ */
+class UnauthorizedException(message: String, val response: HttpResponse, e: Throwable) : ApiException(message, e)
+
 /**
  * Represents a client based exception that occurred when interacting with the API.
  * This is usually the result of a non-200 HTTP response code.
@@ -15,6 +20,4 @@ class ApiClientException(message: String, val response: HttpResponse, e: Throwab
     fun statusCode(): Int {
         return response.status.value
     }
-}
-
-class MissingSessionTokenException : Exception("No session token provided")
+}

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

@@ -1,19 +1,13 @@
 package com.ctrlhub.core.assets.vehicles
 
-import com.ctrlhub.core.Config
-import com.ctrlhub.core.api.ApiClientException
-import com.ctrlhub.core.api.ApiException
+import com.ctrlhub.core.Api
 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
-import io.ktor.client.call.body
-import io.ktor.client.plugins.ClientRequestException
+import io.ktor.client.*
 
-class VehicleCategoriesRouter(httpClient: HttpClient) : Router(httpClient, requiresAuthentication = true) {
-    private val endpoint = "${Config.apiBaseUrl}/v3/assets/vehicles/categories"
+class VehicleCategoriesRouter(httpClient: HttpClient) : Router(httpClient) {
+    private val endpoint = "/v3/assets/vehicles/categories"
 
     /**
      * Retrieve all vehicle categories
@@ -23,22 +17,9 @@ class VehicleCategoriesRouter(httpClient: HttpClient) : Router(httpClient, requi
      * @return A list of vehicle categories
      */
     suspend fun all(requestParameters: RequestParameters = RequestParameters()): List<VehicleCategory> {
-        return try {
-            val rawResponse = performGet(endpoint, requestParameters.toMap())
-            val resourceConverter = ResourceConverter(VehicleCategory::class.java).apply {
-                enableSerializationOption(SerializationFeature.INCLUDE_RELATIONSHIP_ATTRIBUTES)
-            }
-
-            val jsonApiResponse = resourceConverter.readDocumentCollection<VehicleCategory>(
-                rawResponse.body<ByteArray>(),
-                VehicleCategory::class.java
-            )
-
-            jsonApiResponse.get()!!
-        } catch (e: ClientRequestException) {
-            throw ApiClientException("All vehicle categories request failed", e.response, e)
-        } catch (e: Exception) {
-            throw ApiException("All vehicle categories request failed", e)
-        }
+        return fetchJsonApiResources(endpoint, requestParameters.toMap())
     }
-}
+}
+
+val Api.vehicleCategories: VehicleCategoriesRouter
+    get() = VehicleCategoriesRouter(httpClient)

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

@@ -1,18 +1,12 @@
 package com.ctrlhub.core.assets.vehicles
 
-import com.ctrlhub.core.Config
-import com.ctrlhub.core.api.ApiClientException
-import com.ctrlhub.core.api.ApiException
+import com.ctrlhub.core.Api
 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
-import io.ktor.client.call.body
-import io.ktor.client.plugins.ClientRequestException
+import io.ktor.client.*
 
 enum class VehicleManufacturerIncludes(val value: String) : JsonApiIncludes {
     Categories("categories");
@@ -25,8 +19,8 @@ enum class VehicleManufacturerIncludes(val value: String) : JsonApiIncludes {
 /**
  * A vehicles manufacturer router that deals with the vehicle manufacturers realm of the Ctrl Hub API
  */
-class VehicleManufacturersRouter(httpClient: HttpClient) : Router(httpClient, requiresAuthentication = true) {
-    private val endpoint: String = "${Config.apiBaseUrl}/v3/assets/vehicles/manufacturers"
+class VehicleManufacturersRouter(httpClient: HttpClient) : Router(httpClient) {
+    private val endpoint: String = "/v3/assets/vehicles/manufacturers"
 
     /**
      * Retrieve all vehicle manufacturers
@@ -36,42 +30,13 @@ class VehicleManufacturersRouter(httpClient: HttpClient) : Router(httpClient, re
      * @return A list of vehicle manufacturers
      */
     suspend fun all(requestParameters: RequestParameters = RequestParameters()): List<VehicleManufacturer> {
-        return try {
-            val rawResponse = performGet(endpoint, requestParameters.toMap())
-            val resourceConverter = ResourceConverter(VehicleManufacturer::class.java).apply {
-                enableSerializationOption(SerializationFeature.INCLUDE_RELATIONSHIP_ATTRIBUTES)
-            }
-
-            val jsonApiResponse = resourceConverter.readDocumentCollection<VehicleManufacturer>(
-                rawResponse.body<ByteArray>(),
-                VehicleManufacturer::class.java
-            )
-
-            jsonApiResponse.get()!!
-        } catch (e: ClientRequestException) {
-            throw ApiClientException("All vehicle manufacturers request failed", e.response, e)
-        } catch (e: Exception) {
-            throw ApiException("All vehicle manufacturers request failed", e)
-        }
+        return fetchJsonApiResources(endpoint, requestParameters.toMap())
     }
 
     suspend fun models(manufacturerId: String, requestParameters: RequestParameters = RequestParameters()): List<VehicleModel> {
-        return try {
-            val rawResponse = performGet("$endpoint/$manufacturerId/models", requestParameters.toMap())
-            val resourceConverter = ResourceConverter(VehicleModel::class.java).apply {
-                enableSerializationOption(SerializationFeature.INCLUDE_RELATIONSHIP_ATTRIBUTES)
-            }
-
-            val jsonApiResponse = resourceConverter.readDocumentCollection<VehicleModel>(
-                rawResponse.body<ByteArray>(),
-                VehicleModel::class.java
-            )
-
-            jsonApiResponse.get()!!
-        } catch (e: ClientRequestException) {
-            throw ApiClientException("All vehicle models request failed", e.response, e)
-        } catch (e: Exception) {
-            throw ApiException("All vehicle models request failed", e)
-        }
+        return fetchJsonApiResources("$endpoint/$manufacturerId/models", requestParameters.toMap())
     }
-}
+}
+
+val Api.vehicleManufacturers: VehicleManufacturersRouter
+    get() = VehicleManufacturersRouter(httpClient)

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

@@ -1,18 +1,14 @@
 package com.ctrlhub.core.assets.vehicles
 
 import com.ctrlhub.core.Api
-import com.ctrlhub.core.api.ApiClientException
-import com.ctrlhub.core.api.ApiException
+import com.ctrlhub.core.assets.vehicles.VehicleRequestParameters
 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.FilterOption
 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 com.ctrlhub.core.router.request.RequestParametersWithIncludes
 import io.ktor.client.*
-import io.ktor.client.call.*
-import io.ktor.client.plugins.*
 
 /**
  * Represents JSONAPI includes that are associated for vehicles
@@ -33,10 +29,15 @@ enum class VehicleIncludes(val value: String) : JsonApiIncludes {
     }
 }
 
+class VehicleRequestParameters(
+    filterOptions: List<FilterOption> = emptyList(),
+    includes: List<VehicleIncludes> = emptyList()
+) : RequestParametersWithIncludes<VehicleIncludes>(filterOptions, includes)
+
 /**
  * A vehicles router that deals with the vehicles realm of the Ctrl Hub API
  */
-class VehiclesRouter(httpClient: HttpClient) : Router(httpClient, requiresAuthentication = true) {
+class VehiclesRouter(httpClient: HttpClient) : Router(httpClient) {
 
     /**
      * Request all vehicles
@@ -48,28 +49,11 @@ class VehiclesRouter(httpClient: HttpClient) : Router(httpClient, requiresAuthen
      */
     suspend fun all(
         organisationId: String,
-        requestParameters: RequestParameters = RequestParameters()
+        requestParameters: VehicleRequestParameters = VehicleRequestParameters()
     ): List<Vehicle> {
-        return try {
-            val rawResponse =
-                performGet("/v3/orgs/$organisationId/assets/vehicles", requestParameters.toMap())
-            val resourceConverter = ResourceConverter(Vehicle::class.java).apply {
-                enableSerializationOption(SerializationFeature.INCLUDE_RELATIONSHIP_ATTRIBUTES)
-            }
-
-            val jsonApiResponse = resourceConverter.readDocumentCollection<Vehicle>(
-                rawResponse.body<ByteArray>(),
-                Vehicle::class.java
-            )
-
-            jsonApiResponse.get()!!
-        } catch (e: ClientRequestException) {
-            throw ApiClientException("All vehicles request failed", e.response, e)
-        } catch (e: Exception) {
-            throw ApiException("All vehicles request failed", e)
-        }
+        return fetchJsonApiResources("/v3/orgs/$organisationId/assets/vehicles", requestParameters.toMap())
     }
 }
 
 val Api.vehicles: VehiclesRouter
-    get() = VehiclesRouter(KtorClientFactory.create())
+    get() = VehiclesRouter(httpClient)

src/main/kotlin/com/ctrlhub/core/auth/AuthRouter.kt

@@ -8,24 +8,17 @@ import com.ctrlhub.core.auth.payload.LoginPayload
 import com.ctrlhub.core.auth.payload.LogoutPayload
 import com.ctrlhub.core.auth.response.AuthFlowResponse
 import com.ctrlhub.core.auth.response.CompleteResponse
-import com.ctrlhub.core.http.KtorClientFactory
 import com.ctrlhub.core.router.Router
-import io.ktor.client.HttpClient
+import io.ktor.client.*
 import io.ktor.client.call.*
 import io.ktor.client.plugins.*
-import io.ktor.client.request.delete
-import io.ktor.client.request.get
-import io.ktor.client.request.header
-import io.ktor.client.request.post
-import io.ktor.client.request.setBody
+import io.ktor.client.request.*
 import io.ktor.http.*
-import kotlinx.serialization.encodeToString
-import kotlinx.serialization.json.Json
 
 /**
  * A router that deals with authenticating through the Ctrl Hub API
  */
-class AuthRouter(httpClient: HttpClient) : Router(httpClient = httpClient, requiresAuthentication = false) {
+class AuthRouter(httpClient: HttpClient) : Router(httpClient = httpClient) {
 
     /**
      * Initiates a flow for authentication. This needs to be called first, before completing
@@ -95,7 +88,7 @@ class AuthRouter(httpClient: HttpClient) : Router(httpClient = httpClient, requi
      * @return true if the session could be invalidated successfully, false if not
      * @throws ApiException If an exception occurred whilst attempting to invalidate a session
      */
-    suspend fun logout(): Boolean {
+    suspend fun logout(sessionToken: String): Boolean {
         return try {
             val statusCode = performDelete("${Config.authBaseUrl}/self-service/logout/api", body = LogoutPayload(
                 sessionToken = sessionToken.toString()
@@ -111,4 +104,4 @@ class AuthRouter(httpClient: HttpClient) : Router(httpClient = httpClient, requi
 }
 
 val Api.auth: AuthRouter
-    get() = AuthRouter(KtorClientFactory.create())
+    get() = AuthRouter(httpClient)