kotlin

Looker SDK

The Looker SDK for Kotlin provides a convenient way to communicate with the Looker API available on your Looker server.

NOTICE: The Kotlin SDK is community supported. Please report any issues encountered, and indicate the SDK language in the report.

Getting started

The Looker SDK can be used in a Kotlin application in 3 steps:

• configure
• install
• use

Configure the SDK for your Looker server

Note: The .ini configuration for the Looker SDK is a sample implementation intended to speed up the initial development of Node applications using the Looker API. See this note on Securing your SDK Credentials for warnings about using .ini files that contain your API credentials in a source code repository or production environment.

Create a looker.ini file with your server URL and API credentials assigned as shown in this example.

[Looker]
# Base URL for API. Do not include /api/* in the url
base_url=https://<your-looker-server>:19999
# API 3 client id
client_id=your_API3_client_id
# API 3 client secret
client_secret=your_API3_client_secret

Note: If the application using the Looker SDK is going to be committed to a version control system, be sure to ignore the looker.ini file so the API credentials aren't unintentionally published.

Install the Looker SDK for Kotlin

This Experimental version of the Looker SDK is not published to a Kotlin Package Manager. Currently, the only way to get the source code is by cloning the Looker SDK Codegen repository and use the source code in the kotlin folder.

To ensure you have the version of the SDK that matches your Looker version, you can regenerate methods.kt and models.kt from the root of the repository with the command:

yarn gen kotlin

If this command fails the first time, read the instructions for setting up yarn

Use the SDK in your code

API 4.0 should be used for all strongly-typed languages like Kotlin. (API 4.0 was explicitly created to support languages like Swift and Kotlin.)

When the SDK is installed and the server location and API credentials are configured in your looker.ini file, it's ready to be used. (There are other ways of providing API credentials to the Kotlin SDK. Using an .ini file is a convenient option for development.)

Verify authentication works and that API calls will succeed with code similar to the following:

import com.looker.sdk.ApiSettings
import com.looker.rtl.AuthSession
import com.looker.sdk.LookerSDK

val localIni = "./looker.ini"
val settings = ApiSettings.fromIniFile(localIni, "Looker")
val session = AuthSession(settings)
val sdk = LookerSDK(session)
// Verify minimal SDK call works
val me = sdk.ok<User>(sdk.me())

/// continue making SDK calls
val users = sdk.ok<Array<User>>(sdk.all_users())

Capturing API Error responses

Detailed error responses from the Looker API can be captured using the parseSDKError() function. The following test shows how all error information from an API response can be captured:

@Test
fun testErrorReporting() {
    try {
        val props = ThemeSettings(
            background_color = "invalid"
        )
        val theme = WriteTheme(
            name = "'bogus!",
            settings = props
        )
        val actual = sdk.ok<Theme>(sdk.validate_theme(theme))
        assertNull(actual) // test should never get here
    } catch (e: java.lang.Error) {
        val error = parseSDKError(e.toString())
        assertTrue(error.message.isNotEmpty())
        assertTrue(error.errors.size == 2)
        assertTrue(error.documentationUrl.isNotEmpty())
    }
}

More examples

Additional Kotlin SDK usage examples may be found in the Kotlin Examples folder

Using AuthSession for automatic authentication

Almost all requests to Looker's API require an access token. This token is established when the login endpoint is called with correct API3 credentials for client_id and client_secret. When login is successful, the user whose API3 credentials are provided is considered the active user. For this discussion of AuthSession, we'll call this user the API User.

The settings provided to the AuthSession class include the base URL for the Looker instance, and the API3 credentials. When API requests are made, if the auth session is not yet established, AuthSession will automatically authenticate the API User. The AuthSession also directly support logging in as another user, usually called sudo as another user in the Looker browser application.

API users with appropriate permissions can sudo as another user by specifying a specific user ID in the AuthSession.login() method. Only one user can be impersonated at a time via AuthSession. When a sudo session is active, all SDK methods will be processed as that user.

Environment variable configuration

Environment variables can be used to configure access for the Looker SDK.

A note about security

Any script or configuration file used to provide credentials to your Looker SDK instance needs to be secured.