Functionality Reference
Search…
⌃K

Bubble API Connector

API Connector Reference Guide
The API connector is a plugin built by Bubble which allows us to build our own custom connections to other products which support an API connection. The below outlines the components for the API connector and is meant to be used as a reference to assist with setting up API calls with various forms of authentication.

API Connector components

  1. 1.
    API Name Provide a custom name for the API service you are connecting to. This name is used internally in your application to connect to the service.
  2. 2.
    Authentication Some API calls require authentication. This is the process of verifying who is making the call and must occur before the API connection is established. The Server wants to know if the client is who they claim to be and if they are allowed to access the resources. Select the authentication method to apply to all the calls you define within this API.
  3. 3.
    Shared headers Headers are additional information sent to the server for it to use. This information is provided so that both parties can understand each other. An example header is specifying the format of the content being sent ie. JSON. This information is sent in an encrypted format and sensitive information such as unique API keys should be listed here. Headers common to all the calls can be provided here instead of individually in each call.
  4. 4.
    Shared parameters Parameters are querystring parameters that are added to the end of the URL in an API call. These values are variable and provide the Server with further information to determine the specific data or action requested. Parameters common to all the calls can be provided here instead of individually in each call.
  5. 5.
    Name Provide a custom name for the API call. This name is used internally in your application to connect to the API.
  6. 6.
    Use as How would you like to use the information from the API call in Bubble? Data: you can use the API call in the design tab using ‘Get data from external API’. Action: you can use the API call in the workflow tab in the Plugin section of the Actions dropdown menu.
  7. 7.
    Data Type Define the expected data format of the API response. An API call can return information in a variety of data formats. Bubble natively supports most data formats. The most common data format of the API response is JSON. The data format of the response will be provided in the API documentation.
  8. 8.
    Method This specifies how to interact with the external server. It tells the server what we want to do and every possible call has a predefined Method (this is specified in the API documentation). Calls to an endpoint with the incorrect method results in an error. The supported methods are:
    • Get: asks the server to retrieve a resource Example: retrieve a list of facebook posts
    • Post: asks the server to create a new resource Example: create a new facebook post
    • Put: asks the server to edit or update an existing resource Example: update a facebook post (replace entire identity using the body of the call)
    • Delete: asks the server to delete a resource Example: delete an existing facebook post
    • Patch: asks the server to update an existing resource Example: update a facebook post (only send information to be updated)
  9. 9.
    URL The location of the server.
  10. 10.
    Headers Headers for the specific call can be added here.
  11. 11.
    Body Type Define the data format of the API call’s body. The external API expects the API call’s body to be provided in a specific format. The most common format is JSON. The expected data format will be defined in the API documentation.
  12. 12.
    Querystring Parameter Parameters for the specific call can be added here.
    • The ‘Private’ checkbox means hardcoded. If not checked the parameter can be dynamically updated in the editor. To note, when this box is not checked, this information is sent to the user’s browser and the description of the call can be viewed and is not secure.
    • The ‘Allow Blank’ checkbox prevents the parameter default value from initialization from being sent as a parameter in the URL. If no value is provided, this parameter will be skipped and not included in the URL when making the call.
    • Parameters may not always be required. The checkbox ‘Optional’ means this can be left empty.
  13. 13.
    Body This is the data that we send to the API. It is a JSON object to pass information to the server. Mostly used with POST calls. Additional Checkboxes
  14. 14.
    Attempt to make the call from the browser API call will be run directly from the browser rather than on the Bubble server (this is possible for only public API calls - no private headers or parameters).
  15. 15.
    Include errors in response and allow workflow actions to continue This allows response errors to be handled in the editor. Workflows will continue despite errors and the error object can be used in a dynamic expression. This is useful when a notification with the API error is to be displayed to the user.
  16. 16.
    Capture response headers The request header in the detected data can be captured if important data to be used is stored in them.
  17. 17.
    Import call from cURL cURL is client URL and is a common format of providing example API calls in documentation. This call format can be imported directly into the API Connector to set up a new call.

API Authentication Methods

Authentication occurs before an API exchange can take place. It is required by some API Servers to validate the identity of the client (party making the request) and confirm access to its resources. The following Authentication Methods are built into the API Connector plugin in Bubble.

Private Key Authentication

For Private Key Authentication, a private key must be provided when polling the API. The private key is a unique identifier for the API server to authenticate the client and confirm their approval to access the API and its resources.
There are two methods by which the Private Key can be provided to the API server
  • via the URL The Private Key can be provided in the URL of the API call. eg. https://api.com/v1/example&apiKey=[Key Value] Private Key in URL Terms
    1. 1.
      Key Name Provide the query string parameter name.
    2. 2.
      Key Value Provide the API key value.
    3. 3.
      Development Key Value Provide the development version API key value. This key will be used when the application is run in Development mode.
Private Key in the URL
  • via the Header The Private Key can be provided in the Header of the API call. This method is preferred as it is a more secure way to send the private key information. eg. Authorization:[Key Value] Private Key in the Header Terms
    1. 1.
      Key Name Provide the API header name.
    2. 2.
      Key Value Provide the API key value.
    3. 3.
      Development Key Value Provide the development version API key value. This key will be used when the application is run in Development mode.
Private Key in the Header

Basic Authentication

Basic Authentication involves providing a username and password to the API Server when making a request. This involves sending the credentials in the header in the format of Authorization:Basic <credentials> where credentials is the concatenated string (separated by a colon) ‘username:password’ encoded in a base64 format.

HTTP Basic Auth Terms

HTTP Basic Auth Terms
  1. 1.
    Username Provide the User ID as specified in the API documentation
  2. 2.
    Password Provide the Password as specified in the API documentation.

Open Authorization (OAuth)

OAuth is an open standard for authorization. It provides client applications with secure delegated access by providing access tokens rather than using credentials. An example of an OAuth flow is when a user logs onto a website and it offers the ability to log in via another site’s service such as a Facebook profile or Gmail account. Following this log in flow links to the other website which authenticates your identity and the original site logs you on using this information.

General OAuth Flow

  1. 1.
    App requests authorization for User Data. The user is redirected to an Authentication URL supported by the OAuth service ie. Spotify login. The URL will have parameters with scopes, client ID and redirect URL. Eg. https://accounts.spotify.com/authorize?client_id=[client_ID]&response_type=code&redirect_uri=https://api-connections.bubbleapps.io/version-test/redirect&scope=user-read-email​
  2. 2.
    Receive Authorization Code Once the user successfully logs in, they are redirected to the Bubble App. An Authorization Code is sent as a parameter in the redirect URL which we capture. Eg. https://api-connections.bubbleapps.io/version-test/redirect?code=AQD3sJeHCJlksSNw9hc3slO3b1vq5FMiv3bZraWOYkvTszfOcPRWjr-HBcE-g7ZAbHy6WdUDJUykL0TDWRVvTELWjCyf10oTJMfMi7bPHmtNeWn6jrseO77M3LTcV2OBTI1n4qiCvD8tqEhmjrZQxPKOIhH26HAfPcQEZGLzrq-SaH1_gi-f28uekoJlg-XGm7nsF3lI-Hw3hJZCmfAAal7UNmEGZxx0L-hTx_5Y63Y​
  3. 3.
    Exchange Authorization Code for Access Token We make an API call to the Token API endpoint of the external service to exchange the Authorization Code from step 2 for an Access Token. If relevant, we will also receive a Refresh Token - these are required if the Access Token has an expiry time.
  4. 4.
    Refresh Token API Call We set up an API call to exchange the Refresh Token to receive a new Access Token once it expires (if required).
  5. 5.
    Refresh Token API Call We set up an API call to exchange the Refresh Token to receive a new Access Token once it expires (if required).
The above flow is natively supported in the Bubble API connector by selecting the Authentication method “OAuth2 User-Agent Flow”.

OAuth2 User-Agent Flow Terms

OAuth2 User-Agent Flow Terms
  1. 1.
    App ID Identifier of application
  2. 2.
    App Secret Authentication Token for application
  3. 3.
    Scope Scopes define the amount of access the app has to a user’s account information. These must be provided in the calls.
  4. 4.
    Authentication goes in the header Checkbox if access token is provided in the header
  5. 5.
    Header Key/Token name Input box for format in which the key must be provided.
  6. 6.
    Token is returned as a query string Checkbox if token is returned as a query string.
  7. 7.
    Requesting an access token uses Basic Auth Checkbox if API documentation requires access token request using basic authentication.
  8. 8.
    Login dialog redirect URL the which directs user to service login and consent screen
  9. 9.
    Access token endpoint The URL that is used to exchange the temporary code for an access token.
  10. 10.
    User profile endpoint The API Endpoint used to retrieve the current user’s profile information. Eg. https://api.spotify.come/v1/me
  11. 11.
    User ID key path The key to retrieve the “ID” value from the current user’s profile information endpoint.
  12. 12.
    User email key path The key to retrieve the “email” value from the current user’s profile information endpoint.
​
Resources - Previous
Bubble API - Authentication
Next - Resources
Check if address is within custom defined area on Map
Last modified 6mo ago