Extensions

Extensions enable environment admins to add custom tabs when displaying an API's details in the API Hub. For example, in the screenshot below you can see the Feedback extension/tab.

Clicking on an extension's tab displays an HTML page in an iFrame. That HTML page can be hosted by you or can be uploaded to Rapid's infrastructure. That page can contain any visual elements that you would like. It can call the current API's endpoints, the Platform API's endpoints, or any other API's endpoints. This allows your enterprise to add functionality to your Hub, such as:

• Add a "Settings" tab for a particular API, allowing you to build a friendly user interface that API consumers can use when configuring or using an API.
• Provide an interactive demo of the API. For example, a facial recognition API can be tested by allowing the developer to drag a picture to the extension's page.
• Add an "SDK" or similar tab for an API so that API consumers can download documents (for example, Microsoft Word documents) related to the API. (This functionality can also be achieved, with Rapid hosting the documents, using Assets).
• Display a dashboard related to an API, displaying information not normally shown on the API Hub, such as monitoring information, open Jira issues related to the API, etc.
• Add a user interface used by administrators of the Hub to manage their Hub in a custom way. For example, an extension that calls the Platform API can be used to visually assign multiple APIs to a new category.

The extensions mechanism is simple yet powerful, because you can host any user interface and call any API from your custom page. This allows you to effectively "add your own features" to the API Hub.

An extension can be shown for all APIs in the Hub or can be limited to a single API. You can have multiple extensions (tabs) for each API.

Adding an extension

1. From the Admin Panel, click Settings in the sidebar, then click the Extensions tab near the top of the page.

2. Click the + icon in the lower right. The Add extension dialog appears.

3. At the top of the Add extension dialog, click Link to extension if you are hosting the HTML page and Upload extension if you are uploading a page to be hosted by Rapid. If you are linking to an existing page, include its URL in the textbox. If you are uploading an HTML page and related Javascript (for example <script src="script.js" async defer>) and CSS pages (for example <link rel="stylesheet" href="styles.css">, your upload must be a ZIP file and must include an index.html document.

   If you upload a ZIP file, you can include files of any type in your ZIP file and link to them in your index.html page. API consumers can then download the file from your extension. For example, the following link can be used to download a Microsoft Word document (notice the download attribute): <a href="mysdk.docx" download>Download the SDK</a>. (This functionality can also be achieved using Assets).

📘

Sample extension page

As a simple example, the extension below links to a Google form. Rapid does not monitor the responses to this form.

4. For Extension name, enter a unique name for the extension. This name is used in the URL when displaying the custom extension/tab, and is displayed in the Admin Panel under Extensions.
5. Optionally enter a Description for the extension. This provides more information about the extension to other environment admins.
6. For Tab label, enter the name of the tab that will be shown to API consumers. In the example below, the tab label is "Feedback".

7. Click the Global extension radio button if this extension should appear as a tab on every API in the Hub. Click Specific page if the extension should only be shown for a single API. You then paste a portion of the URL copied from the API Hub when viewing the details of the API. This is a relative URL starting with a /. For example, /[your-team]/api/[your-api]. The specific page URL does not include a trailing /.
8. If you would like the extension to be visible only when users are logged in to the Hub, slide the Visible only to logged in users to the right.
9. Click Save to add your extension. You should then see your new extension listed. Notice that you can disable, edit or remove your new extension.

Using an extension

Once you have added an extension to your Hub, API consumers will see the new tab when viewing any API (for global extensions) or the specific API (for specific pages). In the example below, the tab is named "Feedback". When an API consumer clicks on the tab, they will see two dropdown boxes. These allow the API consumer to select the correct context and app when viewing/using the extension. These dropdown elements are part of the main Rapid page - the iFrame with custom content begins just below them.

The context dropdown (on the left below) allows API consumers to select which team or personal context they want to use if the extension makes API calls to the API's endpoints.

The app dropdown (on the right below) specifies which app is used for the API calls. Apps are created and used as part of the Developer Dashboard (Apps) and have one or more keys or Authorizations associated with them. If a team or user has only one app associated with it, the dropdown will contain only a single item.

Note: If the API consumer has selected values for the context and app dropdowns on the Endpoints tab (see screenshot below), those values will also be selected on the extension's tab.

These dropdown elements are mainly used to ensure that the correct API key is used for any API calls. The logged in userId and apiKey (as well as the apiId) are passed as query string parameters to the extension's iFrame. The extension can then use the apiKey to make calls to the associated API (more information on this below).

Creating an extension

When an API consumer clicks on a tab related to an extension, an iFrame is loaded in the browser. That iFrame includes your custom user interface code and optionally calls to API they are viewing. To provide context information to use in your custom code, Rapid appends the following query string parameters when calling the iFrame:

userId - The Rapid user id for the currently logged in user.
apiId - The unique ID for the API that is currently being viewed on the API Hub.
apiKey - A comma separated string containing the API key or keys given the context and app that the API consumer currently has selected. Changing the values in the context and app dropdown elements changes the API key.

This information can be obtained in your JavaScript code for the extension using code similar to the following:

// read the query string parameters passed from Rapid
const params = new Proxy(new URLSearchParams(window.location.search), {
    get: (searchParams, prop) => searchParams.get(prop),
});

const apiKey = params?.apiKey?.split(',')[0]; // there may be multiple API keys in an app
console.log('userId = ' + params.userId);
console.log('apiId = ' + params.apiId);
console.log('apiKey = ' + apiKey);

To get started using those values, you could display them on your extension page:

You can then use the API key to call the currently displayed API's endpoints:

// read the query string parameters passed from Rapid
const params = new Proxy(new URLSearchParams(window.location.search), {
    get: (searchParams, prop) => searchParams.get(prop),
});

const apiKey = params?.apiKey?.split(',')[0]; // there may be multiple API keys in an app

const options = {
    method: 'GET',
    headers: {
        'X-RapidAPI-Host': '[your API slug].[your subdomain].rapidapi.com',
        'X-RapidAPI-Key': apiKey
    }
};

fetch('https://[your API slug].p.rapidapi.com/[your endpoint]', options)
    .then(response => response.json())
    .then(response => console.log(JSON.stringify(response))
    .catch(err => console.error(err));

📘

Supporting dark and light mode with your extension

To ensure that the text on your extension's page is readable, it is recommended that you set the color and background-color CSS elements for your page's HTML element.