The Kloudless API Explorer is the most convenient way to test out all the capabilities the Kloudless API has to offer! It provides an interactive counterpart to the detailed documentation in our API Docs.
In this blog post, we’ll explore how the API Explorer is built, and how to use it.
Under the hood
As you may have already guessed, the API Explorer is powered by Swagger UI, which renders the OpenAPI spec that our server generates on the page in the form of API endpoints that can be queried.
However, Kloudless has multiple APIs, each of which represent an abstraction over software applications in a specific category. For example, we offer a unified API for cloud storage services, as well as another for CRM services. It didn’t make sense for us to group all these endpoints into a single OpenAPI specification, so we decided to split it up.
The tabs you see represent those APIs. Each tab requests a unique OpenAPI spec from our API server dynamically and renders it on the page.
We made an early decision to include an API Explorer on our site instead of directing users to third-party tools that help with testing APIs. The largest benefit of this is that we can add additional Kloudless-specific functionality to the API Explorer page to improve the speed with which API requests can be tested and the overall experience of exploring the API.
Here are some of the additional capabilities you can find in the sections above the API Explorer:
- Connecting user accounts using configurable OAuth scopes.
- Auto-populating Account IDs in the Swagger UI based on the one selected.
- Authorizing API requests with account, application-wide, or developer-wide levels of access.
- Sending custom headers, receiving raw data, or impersonating individual users within admin accounts.
Below, we’ll explore some of these capabilities
Using the API Explorer
Connect an account
The first step to testing API requests to an end-user account is connecting it using the Kloudless OAuth flow, which abstracts away the specifics of how authentication works with each individual service provider. The API Explorer allows you to connect your own account to test out how this would work. In an actual application, you would instead use the Authenticator JS library or send the user through a two or three legged OAuth flow as described in the docs.
The advanced settings allow the settings for the OAuth flow to be customized, including scopes, connecting to on-prem services (Enterprise only), and authenticating with sandbox environments instead (Development mode). Connect a regular account to gain access to that user’s data, or an admin account for org-wide access to data.
Accounts are connected to individual Kloudless applications. When logged in, the dropdown automatically populates with the list of Kloudless applications in your account. Alternatively, you may add in any custom Application ID, which is helpful when testing account connectivity to any other application.
Authorize API requests
The result of the account connection process is a Bearer token that provides access to the account. This is auto-populated in the account authorization section. Select an account, or enter in any bearer token, for the Swagger UI to automatically update to use that authorization during API requests.
An alternate form or authentication is using an application-wide token (or “API Key”). This App-wide token allows access to any of the accounts connected to an application and is discouraged for production use for that reason when accessing a specific account. However, it is helpful when testing requests via the API Explorer or when accessing application data that isn’t specific to a single account.
For example, you can list out all accounts connected to your application using application-wide authorization, and then use an Account ID returned in subsequent API requests to retrieve data within that user account. If you’d like to do something similar in production with accounts that have already been verified, use the token exchange endpoint to generate an account-specific token using a larger scoped one.
Perform API requests
The next section provides the ability to add custom headers to API requests. This is helpful for several Core API features, such as impersonating individual users within an admin account that provides org-wide access, or sending/receiving raw data specific to a single connector.
Expand a Swagger UI endpoint to try out API requests to that endpoint.
There are a number of ways we can continue to improve the developer experience using our API Explorer. Here’s some of the feedback we’ve received so far:
- Only display API endpoints applicable to the account selected.
- Add more API documentation from the Docs to the API Explorer.
- Hyperlink IDs to their metadata endpoints.
Have any feedback of your own? Send a note to us at firstname.lastname@example.org! We’d love to hear from you.