Algolia Search API Client for Kotlin

Algolia is a powerful search-as-a-service solution, made easy to use with API clients, UI libraries,and pre-built integrations. Algolia API Client for Kotlin lets you easily use the Algolia SearchREST API from your JVM project, such as Android or backend implementations.

License

License

MIT
Categories

Categories

Kotlin Languages CLI User Interface Search Business Logic Libraries
GroupId

GroupId

com.algolia
ArtifactId

ArtifactId

algoliasearch-client-kotlin-android
Last Version

Last Version

1.4.0
Release Date

Release Date

Type

Type

aar
Description

Description

Algolia Search API Client for Kotlin
Algolia is a powerful search-as-a-service solution, made easy to use with API clients, UI libraries,and pre-built integrations. Algolia API Client for Kotlin lets you easily use the Algolia SearchREST API from your JVM project, such as Android or backend implementations.
Project URL

Project URL

https://github.com/algolia/algoliasearch-client-kotlin
Source Code Management

Source Code Management

https://github.com/algolia/algoliasearch-client-kotlin

Download algoliasearch-client-kotlin-android

How to add to project

<!-- https://jarcasting.com/artifacts/com.algolia/algoliasearch-client-kotlin-android/ -->
<dependency>
    <groupId>com.algolia</groupId>
    <artifactId>algoliasearch-client-kotlin-android</artifactId>
    <version>1.4.0</version>
    <type>aar</type>
</dependency>
// https://jarcasting.com/artifacts/com.algolia/algoliasearch-client-kotlin-android/
implementation 'com.algolia:algoliasearch-client-kotlin-android:1.4.0'
// https://jarcasting.com/artifacts/com.algolia/algoliasearch-client-kotlin-android/
implementation ("com.algolia:algoliasearch-client-kotlin-android:1.4.0")
'com.algolia:algoliasearch-client-kotlin-android:aar:1.4.0'
<dependency org="com.algolia" name="algoliasearch-client-kotlin-android" rev="1.4.0">
  <artifact name="algoliasearch-client-kotlin-android" type="aar" />
</dependency>
@Grapes(
@Grab(group='com.algolia', module='algoliasearch-client-kotlin-android', version='1.4.0')
)
libraryDependencies += "com.algolia" % "algoliasearch-client-kotlin-android" % "1.4.0"
[com.algolia/algoliasearch-client-kotlin-android "1.4.0"]

Dependencies

compile (11)

Group / Artifact Type Version
org.jetbrains.kotlin : kotlin-stdlib-common jar 1.3.72
io.ktor : ktor-client jar 1.3.2
io.ktor : ktor-client-logging jar 1.3.2
io.ktor : ktor-client-core jar 1.3.2
io.ktor : ktor-client-json jar 1.3.2
io.ktor : ktor-client-serialization jar 1.3.2
org.jetbrains.kotlin : kotlin-stdlib-jdk8 jar 1.3.72
io.ktor : ktor-client-core-jvm jar 1.3.2
io.ktor : ktor-client-json-jvm jar 1.3.2
io.ktor : ktor-client-logging-jvm jar 1.3.2
io.ktor : ktor-client-serialization-jvm jar 1.3.2

Project Modules

There are no modules declared in this project.

Algolia for Kotlin

The perfect starting point to integrate Algolia within your Kotlin project

Latest version Licence

DocumentationCommunity ForumStack OverflowReport a bugFAQSupport

Features

  • The Kotlin client is compatible with Kotlin 1.4.0 and higher.
  • It is compatible with Kotlin project on the JVM, such as backend and Android applications.
  • It relies on the open source Kotlin libraries for seamless integration into Kotlin projects:
  • The Kotlin client integrates the actual Algolia documentation in each source file: Request parameters, response fields, methods and concepts; all are documented and link to the corresponding url of the Algolia doc website.
  • The client is thread-safe. You can use SearchClient, AnalyticsClient, and InsightsClient in a multithreaded environment.

💡 Getting Started

Install the Kotlin client by adding the following dependency to your gradle.build file:

repositories {
   mavenCentral()
}

dependencies {
   // Search API Client
   implementation "com.algolia:algoliasearch-client-kotlin:$kotlin_client_version"
   // alternately - for Gradle version < 6.0, use the following
   // implementation "com.algolia:algoliasearch-client-kotlin-jvm:$kotlin_client_version"

   // Choose one of the following http client
   implementation "io.ktor:ktor-client-apache:$ktor_version"
   implementation "io.ktor:ktor-client-okhttp:$ktor_version"
   implementation "io.ktor:ktor-client-android:$ktor_version"
   implementation "io.ktor:ktor-client-cio:$ktor_version"
   implementation "io.ktor:ktor-client-jetty:$ktor_version"
}

For full documentation, visit the Algolia Kotlin API Client.

⚠️ Important: starting from version 1.4.0 the library is compatible only with kotlin version 1.3.70 or higher; for previous versions of kotlin, please use version 1.3.1 of the library.
ℹ️ Please follow the migration guide to migrate from 1.4.x or below to the latest version.

Coroutines

All methods performing HTTP calls in the Kotlin client are suspending functions. This means these functions can only be called from a coroutine.

In the example below, a coroutine is launched in the main thread. The context is switched to a thread pool to perform the search HTTP call off the main thread. The response can be manipulated from the main thread.

class Searcher : CoroutineScope {

    override val coroutineContext = Job()

    fun search() {
        launch(Dispatchers.Main) {
            val response = withContext(Dispatchers.Default) { index.search() }
        }
    }
}

The developer is responsible for implementing the asynchronous logic that matches their specific requirements. The Kotlin client doesn't execute HTTP calls on any particular thread, it is up to the developer to define it explicitly using coroutines. Learn more about coroutines.

Waiting for operations

Waiting for an asynchronous server task is made available via a function literal with receiver.

Use the apply or run functions on your index or client.

index.apply {
    setSettings(Settings()).wait()
}
client.run {
    multipleBatchObjects(listOf<BatchOperationIndex>()).waitAll()
}

The wait functions are suspending, and should only be called from a coroutine.

Type safety

Response and parameters objects are typed to provide extensive compile time safety coverage.

Example for creating a Client instance without mixing the application ID and the API key.

val appID = ApplicationID("YourApplicationID")
val apiKey = APIKey("YourAdminAPIKey")

val client = ClientSearch(appID, apiKey)

Example for attributes:

val color = Attribute("color")
val category = Attribute("category")

Query(
  attributesToRetrieve = listOf(color, category)
)

Sealed class are used to represent enumerated types. It allows to quickly discover possible values for each type thanks to IDE autocomplete support. All sealed class have an Other class case for avoiding runtime crashes in case of unforeseen value.

val query = Query()

query.sortFacetsBy = SortFacetsBy.Count
// query.sortFacetsBy = SortFacetsBy.Alpha
// query.sortFacetsBy = SortFacetsBy.Other("unforeseen value")

R8 / Proguard rules

If you use this library in an Android project which uses R8, there is nothing you have to do. The specific rules are already bundled into the JAR, which can be interpreted by R8 automatically.

If however, you don’t use R8 you have to apply the rules from this file.

Guides

Troubleshooting

Encountering an issue? Before reaching out to support, we recommend heading to our FAQ where you will find answers for the most common issues and gotchas with the client.

📄 License

Algolia Kotlin API Client is an open-sourced software licensed under the MIT license.

com.algolia

Algolia

Open source tools for building search. Learn more at community.algolia.com

Versions

Version
1.4.0