Define API call parameters in Bubble's plugin editor to build custom plugins that make API calls, handle authentication, and expose data to the Bubble editor. This tutorial covers creating API calls within plugin elements and actions, defining static and dynamic parameters, configuring authentication, and making response data available as plugin outputs.
Overview: Defining API Call Parameters in the Plugin Editor
This tutorial teaches you how to build Bubble plugins that make external API calls. You will learn to define API calls in the plugin editor, configure parameters (static, dynamic, and private), set up authentication, and expose response data so plugin users can access it in their apps. This is essential for plugin developers extending Bubble's integration capabilities.
Prerequisites
- A Bubble account with access to the Plugin Editor at bubble.io/home/plugins
- An external API you want to connect to
- API credentials (key or OAuth) for the target API
- Basic understanding of REST APIs and JSON
Step-by-step guide
Create a new plugin and navigate to the API calls tab
Create a new plugin and navigate to the API calls tab
Go to bubble.io/home/plugins and click Create a new plugin. Give it a name and description. In the plugin editor, you will see tabs across the top: General, Shared, API calls, Elements, Actions, Settings/Version, and Review. Click on the API calls tab. This is where you define external API connections that your plugin will use. Click Add a new API to start configuring your first call.
Expected result: A new plugin is created and you are on the API calls tab ready to configure your first API connection.
Define the API connection and authentication
Define the API connection and authentication
In the API call configuration, set the API Name (such as Weather API). Choose the authentication method. For API key authentication, select Private key in header and set the header name (such as X-API-Key or Authorization). The key value will be entered by plugin users in the plugin settings. For OAuth, select the appropriate OAuth2 flow and configure the authorization and token URLs. Add any required shared headers like Content-Type: application/json.
Pro tip: Use the Settings tab to create a plugin setting field where users enter their API key. Reference this setting in the authentication header using the dynamic value syntax.
Expected result: The API connection is configured with the correct authentication method and shared headers.
Create API call endpoints with parameters
Create API call endpoints with parameters
Under the API connection, click Add a new call. Set the call name (such as Get Weather), HTTP method (GET), and URL with parameter placeholders in square brackets (such as https://api.weather.com/v1/forecast?city=[city]&units=[units]). Parameters in brackets become dynamic fields that plugin users can fill in. For each parameter, set whether it is a URL parameter, header parameter, or body parameter. Check Private for any parameter containing sensitive data. Check Client safe if the value needs to be dynamic in the Bubble editor but is not sensitive.
Expected result: An API call is defined with named parameters that appear as configurable fields when the plugin is used.
Set the call type and initialize the response
Set the call type and initialize the response
Set the Use as option for each call. Data calls appear as data sources in the Bubble editor (for GET requests that return data). Action calls appear as workflow actions (for POST, PUT, DELETE requests that perform operations). Click Initialize to test the call with sample parameter values. Bubble will execute the call and map the JSON response structure. Review the mapped fields and ensure all needed response fields are detected. If some fields are missing, try initializing with different test data that includes all possible fields.
Expected result: The API call is initialized successfully with all response fields mapped and available in the Bubble editor.
Expose response data through plugin elements or actions
Expose response data through plugin elements or actions
For Data calls, the response fields are automatically available as data sources when a plugin user adds Get data from external API and selects your plugin's call. For Action calls, go to the Actions tab in the plugin editor and create a new action. In the action's server-side code, use the API call results to set return values. Define the action's return type so plugin users can reference the result using Result of step X in their workflows. List each output field with its type (text, number, date, etc.).
Expected result: Plugin users can access API response data either as data sources (for Data calls) or as action return values (for Action calls).
Test the plugin in a Bubble app
Test the plugin in a Bubble app
Create a test Bubble app and install your plugin from the plugin editor by clicking the Install on test app button. In the test app, go to the Plugins tab and configure the plugin settings (enter the API key). Then use the plugin: for Data calls, add a Group or Repeating Group with the data source set to your plugin's API call. For Action calls, create a workflow and add your plugin's action from the Plugins section. Test in preview mode to verify data flows correctly.
Expected result: The plugin's API calls work correctly in a test app, with response data displaying in elements and returning from actions.
Complete working example
1{2 "PLUGIN_API_CONFIGURATION": {3 "api_name": "Weather API",4 "authentication": {5 "method": "Private key in header",6 "header_name": "X-API-Key",7 "header_value": "<from plugin settings>"8 },9 "shared_headers": {10 "Content-Type": "application/json",11 "Accept": "application/json"12 }13 },1415 "CALL_1": {16 "name": "Get Weather Forecast",17 "method": "GET",18 "url": "https://api.weather.com/v1/forecast?city=[city]&units=[units]&days=[days]",19 "use_as": "Data",20 "parameters": [21 {22 "name": "city",23 "type": "URL parameter",24 "private": false,25 "client_safe": true,26 "description": "City name for forecast"27 },28 {29 "name": "units",30 "type": "URL parameter",31 "private": false,32 "client_safe": true,33 "default": "metric"34 },35 {36 "name": "days",37 "type": "URL parameter",38 "private": false,39 "client_safe": true,40 "default": "7"41 }42 ],43 "response_fields": [44 "city (text)",45 "temperature (number)",46 "description (text)",47 "humidity (number)",48 "forecast (list)"49 ]50 },5152 "CALL_2": {53 "name": "Submit Weather Report",54 "method": "POST",55 "url": "https://api.weather.com/v1/reports",56 "use_as": "Action",57 "body": {58 "location": "<location_param>",59 "temperature": "<temp_param>",60 "conditions": "<conditions_param>"61 },62 "return_values": [63 "report_id (text)",64 "status (text)"65 ]66 }67}Common mistakes when defining API call parameters in the Plugin Editor of Bubble.io: Step-by-Ste
Why it's a problem: Not marking API key parameters as Private
How to avoid: Always check the Private checkbox for API keys, tokens, and any sensitive parameter values
Why it's a problem: Initializing with data that does not include all possible response fields
How to avoid: Initialize with test data that returns the most complete possible response, including all optional fields and nested objects
Why it's a problem: Using Data type for calls that modify server state
How to avoid: Use Action type for any call that creates, updates, or deletes data (POST, PUT, PATCH, DELETE). Reserve Data type for read-only GET calls
Best practices
- Use Private key in header authentication for the best security posture
- Mark all sensitive parameters as Private to keep them server-side
- Create plugin settings fields for API keys so each user provides their own credentials
- Initialize calls with comprehensive test data that includes all possible response fields
- Use Data type for read-only GET calls and Action type for state-changing calls
- Document each parameter's purpose and expected format in the parameter description
- Test the plugin thoroughly in a separate test app before publishing
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I am building a Bubble.io plugin that makes API calls to a weather service. I need to define GET and POST calls with parameters for city, date range, and API key authentication. How should I configure the API calls in the plugin editor?
Help me set up a plugin that connects to an external API. I need a GET call that returns data for use in Repeating Groups and a POST call that runs as a workflow action. Show me how to define the parameters and authentication.
Frequently asked questions
Can plugin API calls access Bubble's internal data?
Plugin API calls are for external APIs. To access Bubble data within a plugin, use the plugin's element or action JavaScript code, which has access to Bubble's properties and states.
How do I handle API responses with nested JSON objects?
Bubble's initialization maps nested objects as sub-types. After initialization, you can access nested fields using dot notation in the editor (such as response's weather's temperature).
Can I make authenticated calls where each plugin user has their own API key?
Yes. Create a plugin setting field for the API key. In the API call authentication, reference this setting. Each app that installs the plugin enters their own key in the plugin settings.
How do I handle pagination in plugin API calls?
Define a page or offset parameter on the call. Plugin users can pass the page number dynamically from their workflow. For automatic pagination, use the Action type and handle iteration in the action's server-side code.
Can RapidDev help build custom Bubble plugins?
Yes. RapidDev can help you build and publish custom Bubble plugins with API integrations, custom elements, and workflow actions tailored to your specific needs.
What happens if the external API changes its response format?
You need to re-initialize the API call in the plugin editor to update the field mapping. Plugin users may need to update their apps if field names changed. Version your plugin to communicate breaking changes.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation