Connect external APIs

In a brick, you can fetch data from external APIs and make it available on the brick’s props.

To achieve this, define the getExternalData function on the brick’s schema. This function receives the current page, all the brick’s props, and additional arguments that can be passed when calling the fetchPage function.

It should be an async function that fetches data from external APIs and returns a promise resolving to an object. This object is then merged with the brick’s props, making the external API data available for use within the brick.

Usage Examples

Fetch based on a Page custom field

...
Product.schema = {
  ...
  getExternalData: async (page, brickProps) => {
    const res = await fetch(`https://externalapi/products/${page.customValues.productId}`)
    const product = await res.json()
    return ({
      productName: product.name
      productImage: product.imageUrl
    })
  }
}

Fetchs based on a brick’s prop

import { types } from 'react-bricks/rsc'
import classNames from 'classnames'

interface StockQuoteProps {
  symbol: string
  stockResult: {
    c: number
    d: number
    dp: number
    h: number
    l: number
  }
}

const StockQuote: types.Brick<StockQuoteProps> = ({ symbol, stockResult }) => {
  if (!stockResult) {
    return (
      <div className="text-center text-red-500 underline text-xl">
        Symbol not found!
      </div>
    )
  }

  const { c, d, dp, h, l } = stockResult

  return (
    <div className="my-12 w-52 mx-auto rounded-full border px-6 py-3">
      <div className="flex items-center justify-between">
        <div className="text-black font-bold">{symbol}</div>
        <div className="text-black font-bold">{c?.toFixed(2)}</div>
      </div>
      <div className="flex items-center justify-between">
        <div
          className={classNames(
            'text-sm font-bold',
            dp >= 0 ? 'text-green-500' : 'text-red-500'
          )}
        >
          {dp?.toFixed(2)}%
        </div>
        <div>
          <input
            type="range"
            readOnly
            min={l}
            max={h}
            value={c}
            className="w-24 h-1 bg-gray-200 dark:bg-gray-700 rounded-lg appearance-none [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-2
            [&::-webkit-slider-thumb]:h-2 [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-blue-500"
          />
        </div>
      </div>
    </div>
  )
}

StockQuote.schema = {
  name: 'stock-quote',
  label: 'Stock Quote',

  getExternalData: async (page, brickProps) => {
    const response = await fetch(
      `https://finnhub.io/api/v1/quote?symbol=${brickProps?.symbol}&token=<Your_FinnHub_Token>`,
      { next: { revalidate: 10 } }
    )
    const data = await response.json()

    return {
      stockResult: {
        c: data.c,
        d: data.d,
        dp: data.dp,
        l: data.l,
        h: data.h,
      },
    } as Partial<StockQuoteProps>
  },

  sideEditProps: [
    {
      name: 'symbol',
      label: 'Symbol',
      type: types.SideEditPropType.Text,
    },
  ],
}

export default StockQuote

Result

TypeScript signature

getExternalData?: (
  page: Page,
  brickProps?: T,
  args?: any
) => Promise<Partial<T>>

Arguments

Property	Definition
`page`	The page object for the current page.
`brickProps`	The props for this brick. The generic type is inherited from the brick’s interface.
`args`	Arguments that can be passed from the `fetchPage`, for example to receive a querystring parameter.

Return value

A promise resolving to an object of type Partial<T>, where T is the brick component’s interface. This returned object is merged with the brick’s props.

Use data fetched at Page level

If you defined the getExternalData on the pageType, rather than on the brick’s schema, you can map the external data fetched at page-level to the brick props using the mapExternalDataToProps function.

Usage example

MyBrick.schema = {
  ...
  mapExternalDataToProps: (externalData, bricksProps) => ({
    title: externalData.productName,
    ...
  })
}

`mapExternalDataToProps` Signature

mapExternalDataToProps?: (externalData: Props, brickProps?: T) => Partial<T>

The function receives:

The external data fetched at page level
The current brick props

The return value should be an object which gets merged with the brick’s props.