Kotlin API clients
This is documentation for v2 of the Kotlin API clients, which is not the latest version. To see the documentation for the latest version, see Kotlin v3.
Algolia’s Kotlin API client lets you use Algolia’s APIs from your Kotlin app. Compared to using the APIs directly, using the Kotlin API client has these benefits:
-
Network retry strategy. The API client automatically retries connecting to another Algolia server, if the connection fails. Thanks to that, using the API clients is covered by Algolia’s SLA.
-
Reindexing. The API clients let you reindex your records in a single operation.
The Kotlin API client is built on top of these Kotlin libraries:
- Kotlin multiplatform.
- Kotlinx serialization for json parsing.
- Kotlinx coroutines for asynchronous operations.
- Ktor HTTP client.
Install the Kotlin API client
The Algolia Kotlin API client supports Kotlin version 1.6 or later. The API client supports both JVM (backend) and Android (frontend) projects.
Install the Kotlin API client by adding the following dependencies to your build.gradle.kts
file:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
dependencies {
// for Gradle version 6.0 and later
implementation("com.algolia:algoliasearch-client-kotlin:2.0.0")
// Choose one of the following HTTP clients
// For JVM:
implementation("io.ktor:ktor-client-apache:2.0.1")
implementation("io.ktor:ktor-client-java:2.0.1")
implementation("io.ktor:ktor-client-jetty:2.0.1")
// For JVM/Android
implementation("io.ktor:ktor-client-okhttp:2.0.1")
implementation("io.ktor:ktor-client-android:2.0.1")
implementation("io.ktor:ktor-client-cio:2.0.1")
}
For serializing and deserializing your records, add the following plugin to your build.gradle.kts
file:
1
2
3
4
plugins {
// ...
kotlin("plugin.serialization") version "1.6.21"
}
Test your installation
If you haven’t already, create an Algolia account and create a new Algolia app to get started.
To test whether you can connect to Algolia, run a simple program that adds a record to a new index, searches the index, and print the results.
-
Copy the following code into a text editor. If you’re signed in, the code samples below show your Algolia application ID. If you’re not signed in, replace
YourApplicationID
with your Algolia application ID andYourWriteAPIKey
with your Write API Key. You can find both in your Algolia account.Copy1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
// Main.kt import com.algolia.search.client.ClientSearch import com.algolia.search.helper.deserialize import com.algolia.search.model.APIKey import com.algolia.search.model.ApplicationID import com.algolia.search.model.IndexName import com.algolia.search.model.ObjectID import com.algolia.search.model.indexing.Indexable import com.algolia.search.model.search.Query import kotlinx.serialization.Serializable // A simple record for your index @Serializable private data class Record( val name: String, override val objectID: ObjectID ) : Indexable suspend fun main() { // Connect and authenticate with your Algolia app val client = ClientSearch( applicationID = ApplicationID("YourApplicationID"), apiKey = APIKey("YourWriteAPIKey") ) // Create a new index and add a record (using the `Record` class) val index = client.initIndex(indexName = IndexName("test_index")) val record = Record("test_record", ObjectID("1")) index.run { saveObject(Record.serializer(), record).wait() } // Search the index and print the results val response = index.run { search(Query("test_record")) } val results: List<Record> = response.hits.deserialize(Record.serializer()) println(results[0]) }
-
Build and run the project.
-
If the program ran successfully, you should see:
Copy1
Record(name=foo, objectID=1)
You can inspect your index now in the Algolia dashboard.
Next steps
Now you can interact with the Algolia Search API, you can look at the available methods, for example, for search or indexing.
Other APIs, for example for Algolia Recommend or Analytics, come with their own clients. To get an overview, see Initialize the Kotlin API client.