Looker supports several APIs. The most current API - APIv3 - is still in beta, but all development should take place with this. The API documentation can be obtained by going to the Admin page for your Looker instance and choosing “API” under the “Server” settings category in the second column. Currently it is the last option in that list so you will need to scroll to the end.
By default the APi is accessed using the same URL as your Looker server, but at port 19999 instead of port 9999. If your Looker server is behind a firewall or a load balancer you will want to set up a way to direct traffic to port 19999. You may also need to change the URL here to point properly at the API endpoint if you are using a different port or a load balancer.
The port for the API can be set to something other than 19999 using the --core-port=NNNNN directive at startup. You can see all the possible startup directives by running Looker with the --help flag like this:
$ ./looker --help
3.50.9
Options:
-p, --port=<i> Port to run on (default: 9999)
--core-port=<i> Port to run core on (default: 19999)
--core-on-loopback Expose Core API on loopback interface
...
If the flag --core-on-loopback is set, then the API calls will only be available on the loopback network device. In other words, only a process on the machine running Looker and attempting to call the API via 127.0.0.1 or localhost will be able to access it. Unless you have set up some special networking config such as using an ssh tunnel to forward API connections, you probably don’t want this.
Assuming the “API Host URL” is set properly, you should be able to click the “View API Docs” link and see the online documentation for the API.
In order to use the API calls, you need to go to the “Users” screen in the “Admin” section and obtain a special set of credentials that are only used with the API. You can either get credentials that are associated with a “real” user or you can create an API only user.
The real user’s API credentials can be obtained by editing that user, then pressing the “New API 3 Key” button. A real user can have several API 3 Keys. By setting several keys, a user can have a separate key for each application that may connect as that user. In this way individual applications can be de-authorized without affecting others. The API operations will run with the exact same permissions as the real user.
The “API Only User” is not associated with a real user. These users have a single API 3 Key. Since they are not associated with any particular user, the API Only User needs to have the permissions and roles set explicitly.
The Client ID and Client Secret which make up the API 3 Key obtained from here can then be entered at the top of the API documentation screen and used to test the various API operations.
At the top right of the API Documentation screen is a set of buttons that allow you to see the SDK and HTTP versions of the various API calls. The SDK version is used to call the API from a library in your client code. The HTTP version is used to call the API via direct HTTP (or more likely HTTPS) calls.
If you are logged into the API documentation screen, you can try any of the API calls right there. For instance, this is a call to retrieve the id and title of all the saved looks on the system:
Pressing the “Try it out!” button will invoke the API call, and the request and response will be shown below:
Many of the HTTP API calls use rely on providing a JSON document with an HTTP POST or PATCH operation. The values that need to be provided are not always obvious. The easiest way to determine what these values look like is to use one of the GET operations to retrieve an object like the one you want to create or modify, then use that object as the model for the POST or PATCH operation. But what is also useful is to look at the “Model” rather than just the “Model Example”.
For example, consider the Create Look operation:
Under the Data Type for the body Parameter is a sample JSON document like the one that will be sent. Clicking the word “Model” right above it however will show additional details.
Any of the parameters marked read-only should not be filled in when creating a new object. The optional parameters need not be provided. The write-only parameters may be filled in when creating the object but should not be expected when retrieving the object.
To use the API from another application, you will need to an SDK client library in a compatible language. Rather than support several different client languages, we use a framework called Swagger which will generate the needed library. So from the same definition document you can create an API library to call from Ruby, from Python, from Java, from .Net, etc. The instructions for using Swagger to generate the library are here: Generating Clients/SDKs Using Swagger Codegen
You can also call the HTTP version of the API. This can enable really simple clients like shell scripts that can be easily called form utilities like “cron”. Here is an example using a shell script and curl to call the API:
#!/bin/bash
CLIENT_ID=YOUR_CLIENT_ID_HERE
CLIENT_SECRET=YOUR_CLIENT_SECRET_HERE
END_POINT=https://learn.looker.com:19999/api/3.0
DASHBOARD=73
DASHBOARD_FILTER='[ { "name": "Date", "value": "20 days" } ]'
jq_location=`which jq`
status=$?
if [ $status -gt 0 ]
then
echo "This utility requires the jq command line utility to parse JSON data. Find more information here: https://stedolan.github.io/jq/"
echo "On a mac with the brew utility installed, you should be able to install jq with the command \"brew install jq\"."
exit 255
fi
echo "Logging in"
response=`curl --request POST --fail --silent --show-error "${END_POINT}/login?client_id=${CLIENT_ID}&client_secret=${CLIENT_SECRET}"`
status=$?
if [ $status -gt 0 ]
then
echo "Failed logging in"
exit 1
fi
ACCESS_TOKEN=`echo $response | jq --raw-output '.access_token'`
echo "Got access token \"${ACCESS_TOKEN}\""
echo "Setting the load_configuration"
response=`curl --request PATCH --fail --silent --show-error --header "Authorization: token ${ACCESS_TOKEN}" --data "{ \"load_configuration\": \"prefetch_cache_run\" }" "${END_POINT}/dashboards/${DASHBOARD}"`
status=$?
if [ $status -gt 0 ]
then
echo "Failed setting load_configuration"
exit 2
fi
echo "Creating the prefetch"
response=`curl --request POST --fail --silent --show-error --header "Authorization: token ${ACCESS_TOKEN}" --data "{ \"ttl\": 6000, \"dashboard_filters\": ${DASHBOARD_FILTER} }" "${END_POINT}/dashboards/${DASHBOARD}/prefetch"`
status=$?
if [ $status -gt 0 ]
then
echo "Failed creating prefetch"
exit 3
fi
echo "Requesting the prefetch"
response=`curl --request GET --fail --silent --show-error --header "Authorization: token ${ACCESS_TOKEN}" --data-urlencode "dashboard_filters=${DASHBOARD_FILTER}" "${END_POINT}/dashboards/${DASHBOARD}/prefetch"`
status=$?
if [ $status -gt 0 ]
then
echo "Failed getting prefetch"
exit 4
fi
echo "First 20 lines of response"
echo $response | jq '.' | head -20
echo "Loggin out"
curl --request DELETE --header "Authorization: token ${ACCESS_TOKEN}" "${END_POINT}/logout"