Integrating External APIs in the Subscription Manager

This guide provides an approach for extending the functionality of the Subscription Manager by integrating external APIs. By following the steps outlined, you can dynamically pull in additional data and render it within your application.

Basic Usage

Step One — Add Function to script.js for API Request

First, add an asynchronous function to script.js that uses the Fetch API to request data from an external API. In this example, we’ll use a URL of a cat image.

1
async function get_cat_url() {
2
  const response = await fetch('https://api.thecatapi.com/v1/images/search');
3
  const [{ url: catUrl }] = await response.json();
4
  return catUrl;
5
}

Step Two — Add Function to script.js to Render Dynamic Content

Next, add a function that returns a template literal with a value from the API response. Utilize the html function from lit-html to interpret and render the template literal efficiently.

1
async function render_cat_image() {
2
  const catUrl = await get_cat_url();
3
  return window.og.smi.html`<img src="${catUrl}" alt="cat" />`;
4
}

Step Three — Call the Render Function from a Liquid Partial

Finally, call the function from the desired location in the liquid template. Chain a call to until to ensure placeholder content is rendered until the asynchronous function resolves.

1
{{ 'render_cat_image()' | js | until }}

Additional Usage

Pass Arguments to Functions

Static Argument

1
{{ 'render_cat_image("tabby")' | js | until }}

Dynamic Argument from Partial Scope

In the example below, we assume order is in scope.

1
{{ 'render_cat_image(order.public_id)' | js | until }}

Set API Response as Variable in a Liquid Partial

1
{% set cat_url = 'get_cat_url()' | js %}

Call API on Button Click

1
<button @click={{ 'get_cat_url' | js }}>
2
  Get Cat URL
3
</button>

Update Application State on API Response

To gracefully update the application state upon receiving an API response, call one of the og.smi API methods to refresh the page state. The example below dispatches an action to request all processing and upcoming orders and updates the application state accordingly.

1
async function get_cat_url() {
2
  const response = await fetch('https://api.thecatapi.com/v1/images/search');
3
  const [{ url: catUrl }] = await response.json();
4
  window.og.smi.api.refresh_page_state();
5
  return catUrl;
6
}

Call an API Outside the Context of Partials

To make an API call independent of partials — such as a single call during application initialization — invoke the API request function directly from script.js. If the function relies on the presence of the SMI element, call the function from the bootstrap function. The example below fetches a cat URL and appends an image to the SMI element.

1
function bootstrap(el) {
2
  smiElement = el;
3
  append_cat();
4
  ...rest of function
5
}
6
7
async function append_cat() {
8
  const catUrl = await get_cat_url();
9
  const catElement = document.createElement('img');
10
  catElement.setAttribute('src', catUrl);
11
  smiElement.appendChild(catElement);
12
}