Repository files navigation

This Looker Open Source repository is released under the MIT license. By usingthis repository, you agree to the terms of that license, and acknowledge thatyou are doing so at your own risk.

While Looker has developed and tested this code internally, we cannot guaranteethat the open-source tools used by the scripts in this repository have not beenmodified with malicious code.

Important - If you are using the Looker TypeScript SDK, please see thisnote on npmjs.com explaining changes to dependencies and packaging.

The TypeScript and Python SDKs are officially supported by Looker/Google.Issues can be logged here in the GitHub Issues page, but can also be loggedwith Looker Support. The other language SDKs are community supported. Issuesfor these should be logged only in the GitHub Issues page. Details of LookerAPI and SDK support can be found athttps://cloud.google.com/looker/docs/api-sdk-support-policy.

This repository contains:

• TheSDK code generator that generates the source code for Looker SDKs
• Source code for the Looker SDKs produced by the code generator
• Looker SDK source codeexamples
• theAPI Explorer extension that can be installed into a Looker instance
• the stand-aloneAPI Explorer
• theRunIt REST client tester (embedded within API Explorer, typically)
• code generator scripts that require Node (file i/o) to read and write SDK files

We hope to help people who want to use Looker as a platform get up and runningquickly, largely by providing pre-built client SDKs in the most popularlanguages, and implementing consistency across all languages and platforms.

The Looker SDK has several parts:

• TheLooker API, described by anOpenAPIspecification (e.g., theSwagger 2.x representation found athttps://<your-looker-domain>:19999/api/4.0/swagger.json). The 4.0 API isour current & stable API. As of October 2023,3.x has been removed.

• TheLooker API Explorer, an interactive reference, accessible eitherstand-alone atdevelopers.looker.com/api/explorer/,or installable into your Looker instance as an extension from the LookerMarketplace.

• Language SDKs, "smarter" client language classes and methods to improvethe experience of calling the Looker API in various popular coding languages.Some SDKs areLooker-supportedwhereas others are community-supported.

The 4.0 version of the API is the current and stable version of the API. The 3.x API has now beenremoved.

For self-hosted instances on older versions of Looker, please use the corresponding release of `sdk-codegen`` to use API 3.x.

Note: API credentials have not been changed between API 3.x and API 4 and may continue to be referred to as "API3" credentials in the Looker UI, docs, or elsewhere.

TL;DR: don't URL encode your inputs because the SDKs will automatically handleit.

All SDKs URL encode (also known aspercentencoding) input values forpassing to the API endpoints automatically. Furthermore, except for Swift,which has problematic URL decoding support, the other SDKs will avoiddouble-encoding inputs that may already be encoded.

When a specific language SDK has been developed, Looker makes that SDKavailable using the standard package manager for that platform. Currently, thePython SDK and theTypeScript SDK can be installedfrom their respective package managers by following the instructions in theirreadmes.

For the other SDKs in this repository, you can copy and paste the source codeinto a module for your own project. Every SDK will eventually have a deployedpackage version.

If you want to use the generation options for an SDK, read on.

There are three steps for generating an SDK with this project:

• configure alooker.ini file so the LookerAPI specification can be retrieved from your Looker server.

  • Note: previous versions of thelooker.ini file had anapi_versionentry. This is no longer required. The code generator project will read anapi_versions value if that is found, but the SDKs ignore this value. Ifapi_versions is not found in theini file, it defaults to "4.0" forthe generator to produce the definitions for the supported API versions.

• install the code generator project dependencies by running:

yarn installyarn build

The resources required to run the code generator are inpackage.json.

Note: Ifyarn is not installed, usethese instructions to install it.

• run the SDK generator withyarn gen [language]

• Note:Generating Client SDKs for the Looker API describes the legacy, manual steps for generating an API language binding. This project replaces these manual steps, and uses an improved code generator.

The code generator and other scripts and tests read a configuration file calledlooker.ini to fetch the API specification from a server. This configurationfile needs to be in the root folder of the code generator.

To createlooker.ini, copylooker-sample.ini tolooker.ini and fill in the required values. The values forclient_id andclient_secret can be retrieved by navigating tohttps://<your_looker_endpoint>/admin/users, editing your user, editing APIkeys, and clicking the "reveal" button to view yourclient_id andclient_secret. If there are currently no API credentials, they can begenerated by clicking “New API Key.”

For your own source code repositories, be sure to configure your versioncontrol system to ignore the SDK configuration.ini file so it doesn'taccidentally get published somewhere unauthorized people can see it.

Unlike some other OpenAPI code generators, the Looker SDK code generatornever writes access information into SDK source code. All SDKs provided byLooker are designed to receive the credentials required to call API methods viaareadConfig() method that returns a key/value collection, whereclient_idandclient_secret are retrieved, and used only for the time it takes tocomplete a login for authentication token retrieval, then they are immediatelydiscarded from memory.

Note: If a.env file is found, this will override values fromlooker.ini. To use a.env file for configuration instead, copyenv-sample to.env and provide the correct values for theenvironment variables.

Invoke the SDK code generator with the command:

yarn gen

To always use the latest Looker API specification for SDK generation, use:

yarn wipe&& yarn gen

The code generator will:

• read the Looker API configuration(s) from thelooker.ini file.

  • Note: Normally there should only be one (1) entry inlooker.ini. Thisfirst ini section is what is used for the SDKs by default, and also by thecode generator.

• download (if the API specification file is not already present) the LookerAPI specification file(s) from the configured Looker server(s)

• convert (if the converted file is not already present) the downloaded Swagger2 specification file(s) to OpenAPI 3.x

• validate the OpenAPI 3.x file(s)

• by default, call the code generator for each active language

  • To generate one specific language SDK, useyarn gen {language}. Thesupported languages have a factory declared in theGenerators array incodeGenerators.ts

When the generator completes successfully, the output will be similar to:

python  looker    rtl      (run-time library hand-written files here)    sdk      methods.py (automatically generated)      models.py (automatically generated)

Note: If you're unable to download the API specification file becauseyou're using an instance of Looker that is self-signed and errors are thrown,you can explicitly turn off SSL verification by puttingverify_ssl=false inthelooker.ini file configuration section.

To generate a language currently not supported by Looker's SDK code generatorwith the OpenAPI generator:

• configure the desired language incodeGenerators.ts.

• useyarn legacy to call the OpenAPI generator. This will use the OpenAPIgenerator to output files to the./api/* path

Use

yarn run

to see the list of all scripts that can be run by the code generator.

After generation, the generated code might not conform with the code standards.Changes cannot be committed until they pass the lint tests.This can be checked with the following:

yarn lint

For a faster run, only the modified files can be checked with any of thesecommands:

yarn lint-changedyarn lint -qyarn lint --quick

Fixes can automagically be applied with one of the following:

yarn lint-changed-fixyarn lint -q -fyarn lint --quick --fix

Theexamples directory contains code snippets and projects writtenusing the Looker language SDKs. You may find useful code in that repository.and are also welcome to contribute additional examples.

See the official documentation forAPI Troubleshooting suggestions.

In addition to swagger being deprecated, thisvisual guide shows why OpenAPI 3.x is preferred to Swagger 2.x.

Looker improves on the security of the generated code for SDKs byneverstoring your server location or API credentials in the source code generated bythe Looker code generator. The SDKs also provide some customizable support forproviding API configuration values like server location and credentials to theSDK. In every Looker SDK, there is an overrideable method calledreadConfig()that can be customized to retrieve and return SDK configuration values fromyour preferred secure storage location.

Each Looker SDK has existingreadConfig() examples that read from.inifiles or environment variables. These are intended to support a quick startwhen developing with a Looker SDK. If a production environment prohibits secureuse of.ini files or environment variables, another method of retrieving APIconfiguration values is required. The API configuration retrieval functionreadConfig() can be overridden to support alternate storage scenarios.

Typically,client_id andclient_secret are the only key values that willneed to be dynamically retrieved from thereadConfig() override methodbecause the other configuration values are saved in memory by the initializedSDK client. In the near future, there will be additional authentication flows(such as OAuth) supported by Looker SDKs. The dynamic result that is returnedbyreadConfig() can also be useful in those additional scenarios.

A shortTypeScript SDK examplethat customizesreadConfig() is available in the SDK Examples repository.

There is also a Kotlin SDK unit test in this repository with a short example:

classMockSettings(contents:String) : ApiSettings(contents) {overridefunreadConfig():Map<String,String> {returnmapOf("base_url" to baseUrl,"verify_ssl" to verifySSL.toString(),"timeout" to timeout.toString(),"headers" to headers.toString(),"client_id" to mockId,"client_secret" to mockSecret        )    }}

Please consult with the security professionals in your organization todetermine the best way to secure your credentials for your own Looker SDKusage.

To streamline getting started with the Looker SDKs, support for reading SDKcredentials from an.ini file is included as a simple method for providingaccess information (server url and API credentials) to the SDK. If the sourcecode to your Looker SDK application is shared in a version control system, the.ini file should be ignored so it never gets inadvertently published.

If the SDK application using an.ini file is available publicly, download orviewing of this.ini file should also be prohibited by the server hosting theapplication.

If the host environment for a Looker SDK supports environment variables, theSDK can also read environment variables to retrieve the server url and APIcredentials. Environment variables could also be visible to intrusive malwarethat may penetrate your application, so this option for providing credentialsshould also be used with caution.

Environment variables can be used for any SDK runtime that supports readingenvironment variables. Environment variables can be used in the:

• Node version of the TypeScript/JavaScript Looker SDK
• Python SDK
• Swift SDK
• Kotlin SDK
• Go SDK

The following table describes the environment variables. By default, the SDK"namespace" is "LookerSDK" which is converted to UPPERCASE when used for namingenvironment variables.

Configuration variables should be processed as follows:

• if the default configuration.ini file exists, apply the values
• if an environment variable exists, apply the value
• if a configuration value is explicitly in code, apply that value
• if a command-line switch is supported, apply that value