📶

Working with APIs

Bricks for Calling APIs

The following bricks are used to call APIs:

  • GET requests with search parameters: @pixiebrix/get
  • REST requests with data: @pixiebrix/http

Each expose a service parameter where you can optionally pass reference to private or shared integration to perform the authentication. If you use a shared integration, the call will be routed through PixieBrix's API proxy, so that the team credentials are not transmitted to the browser

Selecting and Transforming API Results

If you need to post-process (e.g., reshape) the JSON results of an API call, use the jq processor brick

API Providers

RapidAPI

RapidAPI has a hub of thousands of APIs you can call without having to create a separate account with each provider

In this section, we'll use the Currency Converter API available in the hub as an example

Subscribe to the API

If the API is paid/fremium, subscribe to the API in the hub

Create an Integration for the API

Create a private or shared (teams) integration for the API

  • key: your RapidAPI key
  • host: the host of the API you want to hit. Available on the API's marketplace listing
image

Using the API in a Blueprint

In the services: section of the blueprint, include a rapidapi/api service entry:

services:
	rapidapi: rapidapi/api

Then in a @pixiebrix/get or @pixiebrix/http brick, you can pass in the service. The currency converter API uses a GET REST request:

- id: "@pixiebrix/get"
	config:
    service: "@rapidapi"
		url: https://currency-converter5.p.rapidapi.com/currency/convert
		params:
      amount: 1
			format: json
			from: USD
			to: GBP

Encoding URL parts

If you use the params section of the config, @pixiebrix/get brick will automatically URL encode the values you provide.

Many RESTful APIs however vary the URL path for resources. In these cases, you must manually encode the value to avoid problems with spaces and special characters

Currently, the best way to do this is using the nunjucks template engine support. For the variable, use the urlencode filter followed by a safe filter. The safe filter prevents additional escaping. For more information on these nunjucks filters, see the nunjucks filter documentation

- id: "@pixiebrix/get"
  template: nunjucks
	config:
    service: "@rapidapi"
		url: https://omgvamp-hearthstone-v1.p.rapidapi.com/cards/{{ value | urlencode | safe }}