Introducing the API Explorer: Interactive documentation for the Looker API & SDKs

Izzy Miller, Developer Relations Engineer, Looker

May 13, 2021

In my experience as a developer, the only thing worse than an entirely undocumented API is a poorly documented API. Through no real fault of its own, the API suddenly morphs from an inanimate but trustworthy object into an evil and decidedly sentient creature — I picture it and all its poorly documented friends laughing at me while I try and pass a user_id in the body of a request, knowing full well that I should be supplying it as a query param instead.

Me trying to figure out a poorly documented API

At least that’s what it feels like sometimes. I think of documentation as a sacred three-way pact of trust between the author, the product, and the user. Everyone has a job to do and if everyone does their job as promised, magical things can be done.

But it’s not always that simple, and APIs in particular can make things complex. The request might look one way if you’re making a raw HTTP request, but if you want to use the Python SDK then you actually have to wrap it in a Model, and so on. Intricacies that, once learned, can radically improve code efficiency actually end up presenting as blockers to adoption and initial understanding. That’s not ideal.

Enter the Looker API Explorer

Fortunately, there’s a new, interactive, and easy way to explore the Looker API, prototype requests in the language of your choice, and actually execute API calls: the Looker API Explorer.

The API Explorer in action. Note the language and version selectors.

If you’ve ever used the API docs that are built into a Looker instance, this gives you access to the same information, but includes more interactive features and language-specific information. The API Explorer provides all the details you expect from documentation and then goes beyond that to help developers get from 0 to Hello World as fast as possible.

I’ll highlight three particularly game-changing features and workflows below, but this only scratches the surface. If you’re interested in all the features, I encourage you to install it from the Marketplace and explore around.

Feature #1: “Run It”

Let's be real — you just cannot beat a button labeled “Run It” that lets you execute complex API calls without writing any code. You provide your inputs in a hard-to-mess-up form UI (rather than complex dicts or models), press the button, and then it runs your call. It provides the response in a standard JSON format, but can also return complex formats such as PDFs or PNGs.

I use this all the time. It’s great for simple one-off API calls that don’t require scripting, or testing out a new endpoint. Run It is also an incredibly powerful troubleshooting tool, and I encourage you to use it liberally. If I can’t figure out what’s wrong with a script, my first step now is to run a similar call in the API Explorer and reverse engineer from there.

The Run It UI in action

Feature #2: Language declarations and call syntax

Looker provides SDKs for Python and Typescript, with community-supported SDKs also available for Kotlin, C#, Go, and Swift. Previously, figuring out the syntax for one of these SDKs required digging through github READMEs or package manager pages, and a lot of trial and error.

The API Explorer:

  1. Provides the language declaration for every endpoint as part of the primary documentation, so you can see precisely what the function looks like.
  2. Generates properly formatted ready-to-copy-and-paste code for any API call, using input provided from the Run It UI. (Currently only supports Python & Typescript)
An API Explorer generated call to update_dashboard

I cannot stress enough how much of a game changer this has been for my development workflows. For complex endpoints (like update_dashboard, shown above), having a properly formatted call written for you is like a superpower. Even if you end up tweaking things in your code later, you can’t beat this for getting started with a new endpoint.

Feature #3: Example mining

If encyclopedic information isn’t your cup of tea and you prefer to see real world examples, the Looker API Explorer has your back. Examples for every language are automatically mined from the open-source examples repository and surfaced in each endpoint’s documentation.

Automatically mined examples for the all_dashboards endpoint.

This lets you immediately see in-context examples of the function you’re interested in, and may even link you to an example script that does exactly what you’re hoping to accomplish. Of course, it’s all open-source, so you’re welcome to contribute back your own examples and the list will grow over time.

Getting started with the Looker API Explorer

If you couldn’t already tell, I think the API Explorer is just about the eighth wonder of the world. It has revolutionized the way I develop on the Looker API, and increasingly my answer to internally asked questions is, “Use the API Explorer.”

I’m thrilled to announce that the API Explorer tool is now available in Public Preview to install within Looker. You can head to the Marketplace on your Looker instance to install it (or ask an admin/developer on your instance to do so) and start exploring. Remember, it’s in Beta and we are eagerly awaiting your feedback so we can get to work preparing the final version for General Availability. Try it out, and let us know what you think via in-product feedback!

Next Previous

Subscribe for the latest posts