Re-introducing {API} Explorer (for the first time)
The story of how a Cortex™ hub sample application morphed into a developer onboarding tool.
Note: At this time, API Explorer is available only to select partners. If you are interested in developing a Cortex™ app or integration please register here.
It was February 20, 2018, when a team of engineers, product managers, (and a rather lonely but sincere Developer Advocate) gathered for the first demo of the Cortex™ hub “reference application.” The demo (which itself was a walkthrough of API Explorer) sparked the first of many discussions around OAuth 2.0, schemas and APIs — discussions that would ultimately help shape the final product. What product you ask? Well, the Cortex™ 3rd-party application platform and ecosystem. The ask from product management was simple — develop a sample application that can be used to test the entire Cortex™ 3rd-party app lifecycle, end-to-end.
What isn’t so obvious in the recorded meeting, is that API Explorer would eventually become the de facto tool for developer onboarding and enablement.
In retrospect, this particular demo also highlighted the early stages of the “Developer Zero” journey I had unknowingly embarked on. It’s a little strange now, re-visiting the demo recording. It’s not just listening to the sound of my own voice. There’s an air of insecurity and it’s obvious the platform is in its nascent stages. What isn’t so obvious in the recorded meeting, is that API Explorer would eventually become the de facto tool for developer onboarding and enablement.
“Suck Valley” — Population Everyone?
What’s challenging about this particular flow (or ritual) is that it requires a user agent and an OAuth 2.0 client capable of performing several browser redirects, culminating with the IdP returning a
refresh_token— not exactly “quick start” material.
With over 30 apps published to Cortex™ hub (to date) there’s been plenty of time to collect and curate developer feedback. Without a doubt, the most salient feedback Developer Relations has received is about how challenging it is to implement our OAuth 2.0 authorization flow, and it’s easy to understand why. The particular flavor of OAuth 2.0 supported by Cortex™ hub is referred to as “3-legged OAuth” or the authorization code grant flow. What’s challenging about this particular flow (or ritual) is that it requires a user agent and an OAuth 2.0 client capable of facilitating several browser redirects, culminating with the IdP returning a refresh_token — not exactly “quick start” material.
Don’t get me wrong, it’s not like we wanted to set our developer community up for failure (or worse, sit back and enjoy watching them struggle). There was a good reason why 3-legged OAuth was chosen. It’s a widely used authorization flow that is especially good at empowering end users to consent to 3rd-party apps accessing their data. If you’ve ever installed an app on your phone that prompted for permission to access your camera, or track your location, then you’re quite familiar with this concept.
Enter API Explorer
API Explorer had its own evolutionary process to undergo and it would take several months before it became apparent that an alternative developer onboarding process was needed.
So, API Explorer comes in and saves the day, right? Well, it’s not that simple. API Explorer had its own evolutionary process to undergo and it would take several months before it became apparent that an alternative developer onboarding process was needed. I’ll get to that part, but let’s first take a moment to understand the purpose behind API Explorer and what it’s capable of today.
(WARNING, some light marketing stuff follows)
In short, API Explorer is a simple, yet powerful, Cortex™ Data Lake application, created to empower developers at any stage of their journey.
It can be used to:
- Explore the data available in your Cortex Data Lake
- Rapidly test and refine SQL queries against the Query Service API
- Learn how to parse API responses
- Play in a developer sandbox environment
More than anything, API Explorer reduces the initial friction introduced by having to implement 3-legged OAuth. Basically, the OAuth 2.0 stuff is offloaded to API Explorer so that you can dive straight into exploring and understanding the APIs and the data.
Greasing the Wheels
Ok, since you made it this far, I suppose I’ll share the singular feature that morphed API Explorer into a developer onboarding tool. You ready?
Ok…so what exactly is a “developer token”? And, what makes it so special? In a nutshell, a Developer Token is used to authenticate with API Explorer’s built-in token redemption service. It’s intended to eliminate the need to acquire and store a client_id, client_secret and refresh_token in your own credentials store. Moreover, when combined with one of our SDKs, it can be used in place of these credentials in order to quickly gain API access to your Cortex Data Lake.
So, API Explorer performs the authorization code grant flow, during which you grant it access to your CDL. Then, you generate a developer_token which can be used like an “API key” to send API requests programmatically. Don’t worry — after you’re finished working on your prototype, you’ll have plenty of time left to tackle the 3-legged OAuth flow.
You’re welcome.
Example Usage
Behold! A Cortex™ Data Lake Query Service API request in a few lines of code!
# Export developer token as environment variableexport PAN_DEVELOPER_TOKEN=<your_developer_token>
To learn more about API Explorer and developer tokens, visit our Cortex for Developers site.
Please note that API Explorer is currently available only to select partners. If you’re interested in developing a Cortex™ integration or third-party app register here: https://cortex.pan.dev/register.
