Step 1: Set up for this tutorial Step 2: Create the project Step 3: Write the code Step 4: Build and run the application Next steps

Get started with the SDK for Kotlin

The AWS SDK for Kotlin provides Kotlin APIs for each AWS service. Using the SDK, you can build Kotlin applications that work with Amazon S3, Amazon EC2, DynamoDB, and more.

This tutorial shows you how you can use Gradle to define dependencies for the AWS SDK for Kotlin and then create code that writes data to a DynamoDB table.

Follow these steps to complete this tutorial:

Step 1: Set up for this tutorial
Step 2: Create the project
Step 3: Write the code
Step 4: Build and run the application

Step 1: Set up for this tutorial

Before you begin this tutorial, you need an active AWS account, an AWS Identity and Access Management (IAM) user with a programmatic access key and permissions to DynamoDB, and a Java development environment configured to use that access key as credentials for AWS services.

Follow these steps to set up for this tutorial:

Create an AWS account
Create an IAM user
Install Java and Gradle
Configure credentials

Create an account

If you do not have an AWS account, visit the Amazon Web Services signup page and follow the on-screen prompts to create and activate a new account. For detailed instructions, see How do I create and activate a new AWS account?.

After you activate your new AWS account, follow the instructions in Creating your first IAM admin user and group in the IAM User Guide. Use this account instead of the root account when signing in to the AWS Management Console or making requests to AWS services programmatically. For more information, see Security best practices in IAM in the IAM User Guide.

Create an IAM user

To complete this tutorial, you need to use credentials for an IAM user that has read and write access to DynamoDB. To make requests to AWS services using the AWS SDK for Kotlin, create an access key to use as credentials.

Sign in to the IAM console
In the navigation pane on the left, choose Users. Then choose Add user.
Enter TestSDK as the User name and select the Programmatic access checkbox. Choose Next: Permissions.
Under Set permissions, select Attach existing policies directly.
In the list of policies, select the checkbox for the AmazonDynamoDBFullAccess policy. Choose Next: Tags.
Choose Next: Review. Then choose Create user.
On the Success screen, choose Download .csv.

The downloaded file contains the Access Key ID and the Secret Access Key for this tutorial. Treat your Secret Access Key as a password; save in a trusted location and do not share it.

Note
You will not have another opportunity to download or copy the Secret Access Key.

Install Java and Gradle

Your development environment needs to have Java 8 or later and Gradle installed.

For Java, use Oracle Java SE Development Kit, Amazon Corretto, Red Hat OpenJDK, or AdoptOpenJDK.
For Gradle, go to https://gradle.org/install/.

Configure credentials

Configure your development environment with your Access Key ID and the Secret Access Key. The AWS SDK for Kotlin uses this access key as credentials when your application makes requests to AWS services.

In a text editor, create a new file with the following code:


[default]
aws_access_key_id = YOUR_AWS_ACCESS_KEY_ID
aws_secret_access_key = YOUR_AWS_SECRET_ACCESS_KEY

In the text file you just created, replace YOUR_AWS_ACCESS_KEY with your unique AWS access key ID, and replace YOUR_AWS_SECRET_ACCESS_KEY with your unique AWS secret access key.

Save the file without a file extension. Refer to the following table for the correct location and file name based on your operating system.


Operating system	File name
Windows	`C:\Users\USERNAME\.aws\credentials`
Linux, macOS, or Unix	`~/.aws/credentials`

Step 2: Create the project

To create the project for this tutorial, first use Gradle to create a Kotlin project. Then update the gradle.build.kts file with the required settings and dependencies for the AWS SDK for Kotlin.

To create a new project using Gradle:

Create a new directory called get-started in a location of your choice, for example, your Desktop or Home folder.
Open a terminal or command prompt window and navigate to the get-started directory you created.
Use the following command to create a new Gradle project configuration file (build.gradle.kts) and a basic Kotlin class.
```
gradle init --type kotlin-application --dsl kotlin
```

To configure your project with dependencies for the AWS SDK for Kotlin and DynamoDB

In the folder get-started that you created in the previous procedure, open the build.gradle.kts file.

Replace its contents with the following code, and then save your changes.


import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

plugins {
    kotlin("jvm") version "1.5.30"
    application
}

group = "example.aws"
version = "1.0-SNAPSHOT"

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.0")
    implementation("aws.sdk.kotlin:dynamodb:0.9.4-beta")
    testImplementation(kotlin("test"))
}

tasks.withType<Test> {
    useJUnitPlatform()
}

tasks.withType<KotlinCompile>() {
    kotlinOptions.jvmTarget = "1.8"
}

application.mainClass.set("example.aws.getstarted.AppKt")

The dependencies section contains a dependency to the DynamoDB module of the AWS SDK for Kotlin. The Gradle compiler is configured to use Java 1.8 in the tasks.withType<KotlinCompile>() section.

Step 3: Write the code

After the project has been created and configured, edit the project’s default class App to use the example code below.

In your project folder myapp, navigate to the directory src/main/kotlin/com/example/getstarted. Open the App.kt file.

Replace its contents with the following code and save the file.


package example.aws.getstarted

import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking
import aws.smithy.kotlin.runtime.time.Instant
import aws.smithy.kotlin.runtime.time.epochMilliseconds

import aws.sdk.kotlin.runtime.UnknownServiceErrorException
import aws.sdk.kotlin.services.dynamodb.DynamoDbClient
import aws.sdk.kotlin.services.dynamodb.model.AttributeDefinition
import aws.sdk.kotlin.services.dynamodb.model.AttributeValue
import aws.sdk.kotlin.services.dynamodb.model.CreateTableRequest
import aws.sdk.kotlin.services.dynamodb.model.DynamoDbException
import aws.sdk.kotlin.services.dynamodb.model.KeySchemaElement
import aws.sdk.kotlin.services.dynamodb.model.KeyType
import aws.sdk.kotlin.services.dynamodb.model.ScalarAttributeType
import aws.sdk.kotlin.services.dynamodb.model.TableStatus

fun main() = runBlocking {

    val dynamoDbClient = DynamoDbClient { region = "us-west-2" }
    val newTable = "TestSDK" + Instant.now().epochMilliseconds
    val key = "key"

    try {
        tutorialSetup(dynamoDbClient, newTable, key)

        println("Writing to table...")

        dynamoDbClient.putItem {
            tableName = newTable
            item = mapOf(
                key to AttributeValue.S("${key}_value")
            )
        }

        println("Completed writing to table.")
        println()

        cleanUp(dynamoDbClient, newTable)

    } catch (e: DynamoDbException) {
        println("ERROR (DynamoDbException): " + e.message)
    } catch (e: UnknownServiceErrorException) {
        println("ERROR (UnknownServiceErrorException): " + e.message)
    } finally {
        dynamoDbClient.close()
    }
    println("Exiting...")
}

private suspend fun tutorialSetup(dynamoDbClient: DynamoDbClient, newTable: String, key: String) {

    val createTableRequest = CreateTableRequest {
        tableName = newTable
        attributeDefinitions = listOf(
            AttributeDefinition {
                attributeName = key
                attributeType = ScalarAttributeType.S
            }
        )
        keySchema = listOf(
            KeySchemaElement {
                attributeName = key
                keyType = KeyType.Hash
            }
        )
        provisionedThroughput {
            readCapacityUnits = 10
            writeCapacityUnits = 10
        }
    }
    println("Creating table: $newTable...")
    dynamoDbClient.createTable(createTableRequest)
    println("Waiting for table to be active...")
    var tableIsActive = dynamoDbClient.describeTable {
        tableName = newTable
    }.table?.tableStatus == TableStatus.Active
    do {
        if (!tableIsActive) {
            delay(500)
            tableIsActive = dynamoDbClient.describeTable {
                tableName = newTable
            }.table?.tableStatus == TableStatus.Active
        }
    } while(!tableIsActive)
    println("$newTable is ready.")
    println()
}

private suspend fun cleanUp(dynamoDbClient: DynamoDbClient, newTable: String) {
    println("Cleaning up...")
    println("Deleting table: $newTable...")
    dynamoDbClient.deleteTable {
        tableName = newTable
    }
    println("$newTable has been deleted.")
    println()
    println("Cleanup complete")
    println()
}

Step 4: Build and run the application

After the project is created and contains the example class, build and run the application. To view the table and its data, edit the code to remove the cleanup steps and then rebuild the project.

Open a terminal or command prompt window and navigate to your project directory get-started.
Use the following command to build and run your application:
```
gradle run
```

When you run the application, it calls the CreateTable API operation to create a new table and then calls PutItem to insert a new record into the new DynamoDB table.

Afterward, it will also delete the table.

To see the results in the DynamoDB console

In App.kt, comment out the line cleanUp(dynamoDbClient, newTable) and save the file.
Rebuild the project and write to a new table by running gradle run.
Sign in to the DynamoDB console to view the new item in the newly-created table.

After you view the item in the table, clean up test resources by deleting the table.

Success!

If your Gradle project built and ran without error, then congratulations! You have successfully built your first Kotlin application using the AWS SDK for Kotlin.

Cleanup

When you are done developing with your new application, we recommend terminating or deleting any Amazon Web Services resources you created during this tutorial to avoid incurring any charges. You may also want to delete or archive the project folder (get-started) you created in Step 2.

To clean up the resources you created during this tutorial:

In the DynamoDB console, delete any objects and any buckets created when you ran the application.
In the IAM console, delete the TestSDK user.

If you delete this user, also remove the contents of the credentials file you created during setup.

Next steps

Now that you have the basics down, you can learn about:

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

AWS SDK for Kotlin Developer Preview

Setting up