Appwrite Kotlin SDK

This SDK targets Appwrite server version 2.5.x as shipped on Appwrite Cloud. Self-hosted releases can lag behind Cloud — if you run an older self-hosted build, use a matching older SDK from previous releases when APIs differ.

This is the Kotlin SDK for integrating with Appwrite from your Kotlin server-side code. If you're looking for the Android SDK you should check appwrite/sdk-for-android

Appwrite is an open-source backend as a service server that abstracts and simplifies complex and repetitive development tasks behind a very simple to use REST API. Appwrite aims to help you develop your apps faster and in a more secure way. Use the Kotlin SDK to integrate your app with the Appwrite server to easily start interacting with all of Appwrite backend APIs and tools. For full API documentation and tutorials go to https://appwrite.io/docs

Installation

The SDK requires Java 11 or later and is published to Maven Central as io.appwrite:sdk-for-kotlin. Make sure mavenCentral() is among your repositories, then add the dependency.

Gradle Kotlin DSL (build.gradle.kts):

dependencies {
    implementation("io.appwrite:sdk-for-kotlin:24.0.0")
}

Gradle Groovy (build.gradle):

dependencies {
    implementation 'io.appwrite:sdk-for-kotlin:24.0.0'
}

Maven (pom.xml):

<dependency>
    <groupId>io.appwrite</groupId>
    <artifactId>sdk-for-kotlin</artifactId>
    <version>24.0.0</version>
</dependency>

Getting Started

Init your SDK

Initialize the client with your Appwrite endpoint, project ID and an API key. The endpoint and project ID are on your project's settings page; create an API key with only the scopes your code needs from API Keys in the project sidebar of the Appwrite Console.

import io.appwrite.Client

val client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .setProject("<PROJECT_ID>")
    .setKey("<API_KEY>")

API keys are secrets that bypass user permissions, so use this SDK only in server-side code and never ship a key in a client app. If you self-host Appwrite, use your own endpoint instead, such as https://appwrite.example.com/v1, and call .setSelfSigned(true) only while developing against a server with a self-signed certificate.

Make your first request

Service methods are suspend functions, so call them from a coroutine:

import io.appwrite.Client
import io.appwrite.ID
import io.appwrite.services.Users

suspend fun main() {
    val client = Client()
        .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
        .setProject("<PROJECT_ID>")
        .setKey("<API_KEY>")

    val users = Users(client)

    val user = users.create(
        userId = ID.unique(),
        email = "email@example.com",
        password = "password",
        name = "Walter O'Brien",
    )

    println(user.id)
}

Error handling

Failed requests throw an AppwriteException with message, code, type and response properties:

import io.appwrite.exceptions.AppwriteException

try {
    val user = users.get(userId = "<USER_ID>")
    println(user.name)
} catch (e: AppwriteException) {
    println("${e.code} ${e.type}: ${e.message}")
}

Using the SDK from Java

From Java, pass a CoroutineCallback as the last argument instead of calling the method from a coroutine. Request failures arrive as the callback's error; methods also declare AppwriteException, which Java treats as checked, for invalid arguments.

import io.appwrite.Client;
import io.appwrite.coroutines.CoroutineCallback;
import io.appwrite.exceptions.AppwriteException;
import io.appwrite.services.Users;

Client client = new Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .setProject("<PROJECT_ID>")
    .setKey("<API_KEY>");

Users users = new Users(client);

try {
    users.get("<USER_ID>", new CoroutineCallback<>((user, error) -> {
        if (error != null) {
            error.printStackTrace();
            return;
        }

        System.out.println(user.getName());
    }));
} catch (AppwriteException e) {
    e.printStackTrace();
}

Type safety with models

Methods that return rows, such as listRows and getRow, accept a nestedType so that each row's data is your own class:

import io.appwrite.services.TablesDB

data class Book(
    val name: String,
    val author: String,
    val releaseYear: String? = null,
    val genre: List<String>? = null,
    val isCheckedOut: Boolean,
)

val tablesDB = TablesDB(client)

val result = tablesDB.listRows(
    databaseId = "<DATABASE_ID>",
    tableId = "<TABLE_ID>",
    nestedType = Book::class.java,
)

for (row in result.rows) {
    val book = row.data
    println("${book.name} by ${book.author}")
}

From Java, pass the class before the callback:

try {
    tablesDB.listRows(
        "<DATABASE_ID>",
        "<TABLE_ID>",
        Book.class,
        new CoroutineCallback<>((result, error) -> {
            if (error != null) {
                error.printStackTrace();
                return;
            }

            for (Row<Book> row : result.getRows()) {
                System.out.println(row.getData().getName());
            }
        })
    );
} catch (AppwriteException e) {
    e.printStackTrace();
}

Use appwrite types from the Appwrite CLI to generate these model classes from your database schema. Learn more about type generation.

Every model also has toMap(), which is handy for logging or manual data handling:

val user = users.get(userId = "<USER_ID>")
println(user.toMap())

Learn more

• Kotlin quick start
• Kotlin SDK reference
• Appwrite docs
• Discord community

Contribution

This library is auto-generated by the Appwrite SDK Generator. To learn how you can help improve this SDK, please read the contribution guide before sending a pull request.

License

Please see the BSD-3-Clause license file for more information.