API Blocks

Overview

API Blocks (also known as Dynamic Blocks) allow you to fetch data from any external HTTP endpoint and display it dynamically on your site using an editor template. This enables you to integrate live data feeds, e.g., product lists, news feeds, weather widgets, or payment checkout systems, directly on your site without writing server-side code.

---

Step 1: Create an API Block

To begin, you must define the connection to your external data provider:

1. Open your site dashboard and click the sidebar menu.
2. Select API Blocks from the navigation.
3. Click the New API Block button in the top right.
4. Give your API block a clear, descriptive name (e.g., Product Feed or GitHub Repository Info) and click Create & Configure.

---

Step 2: Configure the API Request

Once created, you will be taken to the API Block Builder, where you can customize the outbound HTTP request:

• Request URL: Enter the endpoint address. You can use placeholder variables using curly braces, e.g., https://api.example.com/items?page={page}.
• HTTP Method: Choose from GET, POST, PUT, PATCH, or DELETE.
• Headers & Parameters: Append static headers (e.g., user agents) or query parameters. You can toggle individual rows on and off like in Postman.
• Request Body: For write methods (POST, PUT, PATCH), you can provide a JSON body template that interpolates user variables.

---

Step 3: Secure Authenticated Endpoints

If your external API requires authentication, do not hardcode your secrets or keys directly in the request headers:

1. Navigate to the Auth tab in the Builder.
2. Click + Add credential.
3. Choose the authentication type:
   • Bearer Token: Appends Authorization: Bearer <token> to requests.
   • API Key: Appends a custom header matching your key (e.g. X-API-Key: <secret>).
   • Basic Auth: Generates a standard base64 username and password header.
4. Allowed Domains: As an essential security measure, specify the exact domain names (e.g., api.stripe.com, dummyjson.com) that this credential is allowed to communicate with. The builder will automatically block calls to unlisted domains to prevent credentials leak.
5. Click Save credential and select it for your request. All credential secrets are encrypted safely at rest.

---

Step 4: Caching Policies

To maintain fast page load times and prevent hitting third-party API rate limits, configure the caching behaviors on the Caching tab:

• TTL (Time to Live): The number of seconds a fetched response remains valid before it needs to be updated.
• Cache Strategies:
  • Cache First: Serves the cached data immediately. The network is only queried if the cache is completely empty.
  • Network First: Always tries to query the live API first. If the request fails or times out, the site falls back to the last cached copy.
  • Stale-While-Revalidate: Serves the cached content instantly to site visitors, and concurrently triggers a background request to fetch fresh data for the next visitor.

---

Step 5: Design Templates (LiquidJS)

In the Template tab, design how your fetched data is rendered on the site using the sandboxed LiquidJS template engine:

1. Root Path: Specify a dot-path to target a nested list or object in the response. For example, if the API returns { "data": { "items": [...] } }, set the Root Path to data.items to bind your template directly to the array.
2. Schema Explorer: Click Send or Test in the request client. The builder will inspect the API response and populate the sidebar with a list of available variables. Click any variable in the list to insert it at your cursor.
3. Liquid Markup: Author your HTML layouts using loops and condition statements:

   {% for product in data.products %}
     <div class="product-card">
       <h3>{{ product.title }}</h3>
       <p>Price: {{ product.price | currency }}</p>
     </div>
   {% endfor %}

4. Formatting Filters: Standard Liquid formatting is supported alongside custom filters:
   • | currency: Formats numbers into currency strings (e.g. {{ price | currency }} becomes $19.99).
   • | dateFormat: Formats ISO date strings (e.g. {{ date | dateFormat }}).

---

Step 6: User Interactions & Behaviors

Define what happens when the block renders or when visitors interact with it on the Behavior tab:

• Trigger:
  • Load: Fetch and render the data immediately when the page mounts.
  • Click: Render an action button first. The request is only sent when the button is clicked.
• Action Kinds:
  • Render: The standard mode. Renders the template output inline.
  • Redirect: Navigates the browser to a URL returned by the API response (e.g., redirecting to a Stripe Checkout URL returned by a payment initialization endpoint).
  • Load More: Appends additional pages of data incrementally when the user clicks the "Load More" button.
  • Paged: Displays numbered pagination buttons to let visitors browse through pages of items.

---

Step 7: Adding API Blocks to Your Pages

To add your configured API block to a page:

1. Open your site's visual page editor.
2. Add the Dynamic API Block element from the block library onto the canvas.
3. Select the block, and open the right sidebar settings.
4. Pick your API Block definition from the selection list.
5. Customize visual styles like width, margins, padding, and hover animation effects (Lift Up, Soft Glow, Zoom).