This article outlines a few ways to consume APIs in custom widgets, with examples.

First, what is an API?

An API is a tool that makes information available to programs in a more convenient format. For example, you can go to a company's website in your browser and see information formatted to look pleasing to the eye.

That same company's API however, presents their information in a way that is convenient for programs. It just gives the information directly.

Below are three examples of how you can use APIs to retrieve information for a custom widget to use however you'd like.

All examples should be included in the JavaScript pane of your custom widget.

jQuery

A powerful feature of jQuery is its straight-forward AJAX functionality. It allows you to easily pull data from not only content within your site, as well as other sites and services.

A call in jQuery looks something like this:

In this AJAX request, we are specifying our endpoint (using the {{ site.url }} Liquid object), and including options to specify that it is a GET with the 'json' datatype. We then bind the data.promotions to our vm.promos to use in our application.

You can learn more about AJAX at W3Schools here.

Fetch API with native JavaScript

The Fetch API provides a simple JavaScript interface for accessing and manipulating parts of the HTTP pipeline, such as requests and responses. The global fetch() method is an easy, logical way to fetch resources asynchronously across a network.

A basic fetch request is really simple to set up. Have a look at the following code:

Here we are fetching a JSON file from within our site using the {{ site.url }} Liquid object. The simplest use of fetch() takes one argument—the path to the resource you want to fetch—and returns a "promise" containing the response (a Response object).

This is an HTTP response, not the actual JSON. To extract the JSON body content from the response, we use the json() method on the end of the response, then bind the data to our promos (this fetch() is for a Promotions application).

For more detailed information, we recommend you check out the MDN webdocs.

Axios

Axios is a very popular JavaScript library that developers use to perform HTTP requests that work in all modern browsers, including support for IE8 and higher.

It's promise-based, and this lets you write async/await code to perform XHR requests easily.

Using Axios has quite a few advantages over the native Fetch API:

• supports older browsers (Fetch needs a polyfill)
• has a way to abort a request
• has a way to set a response timeout
• has built-in CSRF protection
• supports upload progress
• performs automatic JSON data transformation

In order to use Axios in Modyo, you need to add the axios.js source code as a custom snippet and include it somewhere that your widgets can access, such as the javascript theme (located in Templates, under the Assets tab).

Here is an example of an Axios.get() request:

In this example, we are passing two parameters in the get() method. The first is our data endpoint, and the second is an object with our options for the get request. We then use the returned "response" object to bind response.data.promotions to our promos (this is for a Promotions application).

If you still have questions about how to consume APIs in your custom widgets, please submit a request and we'll be happy to help you.