Sometimes folks aren’t sure where to start when they first start using the Looker API’s Ruby SDK. This guide is meant to be a set of quick pointers for using the Ruby SDK for people who are brand new to using it.
How To Use the Ruby SDK
It can be hard to know what the response from a given API call is. Generally, I recommend making the simplest call possible to the endpoint and getting that working, and then closely examining the result that you get. This can often make further API calls more obvious, and it’s easier to catch mistakes that you make later once you add more options and start doing more things with it.
That being said, I’m going to make an effort to include a response model for each endpoint that I cover here so that you know what the response is going to look like.
Responses to the API come in the form of Sawyer objects, from the Sawyer module documented here. Endpoints which return multiple entities (multiple Looks, multiple Users, etc) come in the form of an array, and each entity is a hash with named elements. Technically they come in the form of a Sawyer Resource object, but you access them the same way as arrays and hashes.
API Calls
Authentication
When I authenticate to the API via Ruby, I keep my client ID and client secret in environmental variables (LOOKER_ID and LOOKER_SECRET respectively.
Then, when I write my script, I pull the ID and secret into some credential constants and reference those when I need to authenticate. This allows me to share the scripts with people without having to redact my credentials from the script. It also means that someone can only use my API credentials if they are on my computer and logged in to my account. It’s just kind of a good idea.
I use this basic pattern in every Ruby script that I write, so you’ll be seeing this pattern a lot in my examples.
Another option is to put them in a config file and read the config file into your script. You’re free to pick whichever, this alternative is documented all over the Internet. This is one of the guides that I thought looked best.
require 'looker-sdk'
require 'open-uri'
# Define constants
LOOKER_ID = ENV['LOOKER_ID'],
LOOKER_SECRET = ENV['LOOKER_SECRET']
LOOKER_PATH = 'https://learn.looker.com:19999/api/3.0'
# Define the Looker client
looker = LookerSDK::Client.new(
:client_id => LOOKER_ID,
:client_secret => LOOKER_SECRET,
:api_endpoint => LOOKER_PATH
)
From here, when you call the API endpoints, you’ll use this basic pattern:
looker.<endpoint>
The API client looker is the object, and the endpoint is the method you’re calling on that object. Every call uses the previously defined Looker client object and does the authentication and response handling for you, which takes a lot of the headache out of writing code that leverages the Looker API.
Getting Metadata about a Look
Many of the endpoints on the Looker API give you metadata about some entity in the Looker internal database. One of these is the Looks endpoint. Calling it is pretty straightforward, all you need is the Look ID, which is always in the URL of the current page.
Here is the URL of the Look I want data about:
https://learn.looker.com/looks/2938
And here’s the call I’ll use to pull that data down as JSON:
require 'looker-sdk'
require 'open-uri'
# Define constants
LOOKER_ID = ENV['LOOKER_ID'],
LOOKER_SECRET = ENV['LOOKER_SECRET']
LOOKER_PATH = 'https://learn.looker.com:19999/api/3.0'
# Define the Looker client
looker = LookerSDK::Client.new(
:client_id => LOOKER_ID,
:client_secret => LOOKER_SECRET,
:api_endpoint => LOOKER_PATH
)
my_look = looker.look(2938)
puts my_look.inspect #this last line just prints the JSON to console
Getting Real Data out of a Look
Sometimes you may want to actually run the Look and get the results, instead of just getting data about that Look. You’ll use the Run Look endpoint for this:
require 'looker-sdk'
require 'open-uri'
# Define constants
LOOKER_ID = ENV['LOOKER_ID'],
LOOKER_SECRET = ENV['LOOKER_SECRET']
LOOKER_PATH = 'https://learn.looker.com:19999/api/3.0'
# Define the Looker client
looker = LookerSDK::Client.new(
:client_id => LOOKER_ID,
:client_secret => LOOKER_SECRET,
:api_endpoint => LOOKER_PATH
)
my_data = looker.run_look(2938)
# Data can get really big, so I don't necessarily want to print it all
# You can do whatever you need to do with it from here on out!
Next Steps
There are endpoints for updating Looks with new filter values or queries too. Plus, each “entity” in Looker has its own set of endpoints you can use. For example, you can configure user groups or user attributes via the API, or create and update scheduled plans, or provision new users, or configure new LookML projects. Most things that you can do in the front-end, you can do via the API, in a cooler way. I encourage you to explore each endpoint that looks interesting to you, as this is a really good way to gain a deep understanding of how the API works pretty quickly.
Resources
Looker API reference
Generating SDKs in other languages using Swagger codegen
Official “Getting Started” Guide
