- Bricks for Calling APIs
- Selecting and Transforming API Results
- API Providers
- RapidAPI
- Subscribe to the API
- Create an Integration for the API
- Using the API in a Mod
- Encoding URL parts
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
- Free public APIs
- RapidAPI (including many freemium APIs)
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
Using the API in a Mod
In the services:
section of the mod, 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 }}