Introducing the API Explorer: Interactive documentation for the Looker API & SDKs
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.
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.
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.
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:
Provides the language declaration for every endpoint as part of the primary documentation, so you can see precisely what the function looks like.
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)
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.
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!