Types of APIs

Parabola works best with two types of APIs. The most common API type to connect to is a REST API. Another API type rising in popularity is a GraphQL API. Parabola may be able to connect to a SOAP API, but it is unlikely due to how they are structured.

To evaluate if Parabola can connect with an API, reference this flow chart.

REST API

A REST API is an API that can return data by making a request to a specific URL. Each request is sent to a specific resource of an API using a unique Endpoint URL. A resource is an object that contains the data being requested. Common examples of a resource include Orders, Customers, Transactions, and Events.

To receive a list of orders in Squarespace, the Pull from an API step will make a request to the Squarespace's Orders resource using an Endpoint URL:

https://api.squarespace.com/{api-version}/commerce/orders

GraphQL API

GraphQL is a new type of API that allows Parabola to specify the exact data it needs from an API resource through a request syntax known as a GraphQL query. To get started with this type of API call in Parabola, set the request type to "POST" in any API step, then select "GraphQL" as the Protocol of the request body.

Once your request type is set, you can enter your query directly into the request body. When forming your query, it can be helpful to use a formatting tool to ensure correct syntax.

Our GraphQL implementation current supports Offset Limit pagination, using variables inserted directly into the query. Variables can be created by inserting any single word between the brackets '<%%>'. Once created, variables will appear in the dropdown list in the "Pagination" section. One of these variables should correspond to your "limit", and the other should correspond to "offset."

The limit field is static; it represents the number of results returned in each API request. The offset field is incremented in each subsequent request based on the "Increment each page by" value. The exact implementation will be specific to your API docs.

After configuring your pagination settings, also be sure to adjust the "Maximum pages to fetch" setting in the "Rate Limiting" section as well to retrieve more or less results.

GraphQL can be used for data mutations in addition to queries, as specified by the operation type at the start of your request body. For additional information on Graph queries and mutations, please reference GraphQL's official documentation.

Reading API Documentation

The first step to connect to an API is to read the documentation that the service provides. Oftentimes, the documentation is commonly referred to as the API Reference, or something similar. These pages tend to feature URL and code block content.

The API Reference, always provides at least two points of instruction. The first point outlines how to Authenticate a request to give a user or application permission to access the data. The second point outlines the API resources and Endpoint URLs, or where a request can be sent.

Authentication

Most APIs require authentication to access their data. This is likely the first part of their documentation. Try searching for the word "Authentication" in their documentation.

‍

The most common types of authentication are Bearer Tokens, Username/Password (also referred to as Basic), and OAuth2.0.

Bearer Token

This method requires you to send your API Key or API Token as a bearer token. Take a look at this example below:

The part that indicates it is a bearer token is this:

-H "Authorization: Bearer sk_test_WiyegCaE6iGr8eSucOHitqFF"

Username/Password (Basic)

This method is also referred to as Basic Authorization or simply Basic. Most often, the username and password used to sign into the service can be entered here.

However, some APIs require an API key to be used as a username, password, or both. If that's the case, insert the API key into the respective field noted in the documentation.

The example below demonstrates how to connect to Stripe's API using the Basic Authorization method.

‍

The Endpoint URL shows a request being made to a resource called "customers".  The authorization type can be identified as Basic for two reasons:

1. The -u indicates Basic Authorization.
2. Most APIs reference the username and password formatted as username:password. There is a colon : . This indicates that only a username is required for authentication.

OAuth2.0

This method is an authorization protocol that allows users to sign into a platform using a third-party account. OAuth2.0 allows a user to selectively grant access for various applications they may want to use.

Authenticating via OAuth2.0 does require more time to configure. For more details on how to authorize using this method, read our guide Using OAuth2.0 in Parabola.

Expiring Access Token

Some APIs will require users to generate access tokens that have short expirations. Generally, any token that expires in less than 1 day is considered to be "short-lived" and may be using this type of authentication. This type of authentication in Parabola serves a grouping of related authentication styles that generally follow the same pattern.

One very specific type of authentication that is served by this option in Parabola is called OAuth2.0 Client Credentials. This differs from our standard OAuth2.0 support, which is built specifically for OAuth2.0 Authorization Code. Both Client Credentials and Authorization Code are part of the OAuth2.0 spec, but represent different Grant Types.

Authenticating with the Expiring Access Token option is more complex than options like Bearer Token, but less complex than OAuth2.0. For more details on how to use this option, read our guide Using Expiring Access Tokens in Parabola.

Resources

A resource is a specific category or type of data that can be queried using a unique Endpoint URL. For example, to get a list of customers, you might use the Customer resource. To add emails to a campaign, use the Campaign resource.

Each resource has a variety of Endpoint URLs that instruct you how to structure a URL to make a request to a resource.  Stripe has a list of resources including "Balance", "Charges", "Events", "Payouts", and "Refunds".

‍

‍

HTTP Methods

HTTP methods, or verbs, are a specific type of action to make when sending a request to a resource. The primary verbs are GET, POST, PUT, PATCH, and DELETE.

• The GET verb is used to receive data.
• The POST verb is used to create new data.
• The PUT verb is used to update existing data.
• The PATCH verb is used to modify a specific portion of the data.
• The DELETE verb is used to delete data.

Custom Headers

A header is a piece of additional information to be sent with the request to an API. If an API requires additional headers, it is commonly noted in their documentation as -H.

Remember the authentication methods above? Some APIs list the authentication type to be sent as a header. Since Parabola has specific fields for authentication, those headers can typically be ignored.

Taking a look at Webflow's API, they show two headers are required:

‍

The first -H header is linked to a key called Authorization. Parabola takes care of that. It does not need to be added as a header. The second -H header is linked to a key called accept-version. The value of the header is 1.0.0. This likely indicates which version of Webflow's API will be used.

JSON

JavaScript Object Notation, or more commonly JSON, is a way for an API to exchange data between you and a third-party. JSON is follows a specific set of syntax rules.

An object is set of key:value pairs and is wrapped in curly brackets {}. An array is a list of values linked to a single key or a list of keys linked to a single object.

JSON in API documentation may look like this:

‍

Interpreting cURL

Most documentation will use cURL to demonstrate how to make a request using an API.

Let's take a look at this cURL example referenced in Spotify's API:

curl -X GET "[<https://api.spotify.com/v1/artists?ids=0oSGxfWSnnOXhD2fKuz2Gy>](<https://api.spotify.com/v1/artists?ids=0oSGxfWSnnOXhD2fKuz2Gy,3dBVyJ7JuOMt4GE9607Qin>)"
-H "Authorization: Bearer {your access token}"

‍

We can extract the following information:

• Method: GET
• Resource: artists
• Endpoint URL:

https://api.spotify.com/v1/artists?ids=0oSGxfWSnnOXhD2fKuz2Gy

• Authorization: Bearer token
• Headers: "Authorization: Bearer {your access token}"

Because Parabola handles Authorization separately, the bearer token does not need to be passed as a header.

Here's another example of a cURL request in Squarespace:

This is what we can extract:

• Method: POST
• Resource: products
• Endpoint URL:

https://api.squarespace.com/1.0/commerce/products/

• Authorization: Bearer token
• Headers:

"Authorization: Bearer YOUR_API_KEY_OR_OAUTH_TOKEN", "User-Agent: YOUR_CUSTOM_APP_DESCRIPTION"

• Content-Type: application/json

Parabola also passes Content-Type: application/json as a header automatically. That does not need to be added.

Error Codes

Check out this guide to learn more troubleshooting common API errors.

‍

‍

Basic Settings

To use the Pull from an API step, the "Request Type" and "API Endpoint URL" fields are required.

Request Type

There are two ways to request data from an API: using a GET request or using a POST request. These are also referred to as verbs, and are standardized throughout REST APIs.

The most common request for this step is a GET request. A GET request is a simple way to ask for existing data from an API.

"Hey API, can you GET me data from the server?"

To receive all artists from Spotify, their documentation outlines using GET request to Artist resource using this Endpoint URL:

Some APIs will require a POST request to import data, however it is uncommon. A POST request is a simple way to make changes to existing data such as adding a new user to a table.

The request information is sent to the API in theJSON body of the request. The JSON body is a block that outlines the data that will be added.

Hey API, can you POST my new data to the server?  The new data is in the JSON body.

API Endpoint URL

Similar to typical websites, APIs use URLs to request or modify data. More specifically, an API Endpoint URL is used to determine where to request data from or where to send new data to. Below is an example of an API Endpoint URL.

To add your API Endpoint URL, click the API Endpoint URL field to open the editor. You can add URL parameters by clicking the +Add icon under the "URL Parameters" text in that editor. The endpoint dynamically changes based on the key/value pairs entered into this field.

Authentication

Most APIs require authentication to access their data. This is likely the first part of their documentation. Try searching for the word Authentication in their documentation.

Here are the Authentication types available in Parabola:

The most common types of authentication are Bearer Tokens, Username/Password (also referred to as Basic), and OAuth2.0. Parabola has integrated these authentication types directly into this step.

Bearer Token

This method requires you to send your API Key or API Token as a Bearer Token. Take a look at this example below:

The part that indicates it is a bearer token is this:

-H "Authorization: Bearer sk_test_WiyegCaE6iGr8eSucOHitqFF"

To add this specific token in Parabola, select Bearer Token from the Authorization menu and add "sk_test_WiyegCaE6iGr8eSucOHitqFF" as the value.

Username/Password (Basic)

This method is also referred to as Basic Authorization or simply Basic. Most often, the username and password used to sign into the service can be entered here.

However, some APIs require an API key to be used as a username, password, or both. If that's the case, Insert the API key into the respective field noted in the documentation.

The example below demonstrates how to connect to Stripe's API using the Basic Authorization method.

The Endpoint URL shows a request being made to a resource called customers.  The authorization type can be identified as Basic for two reasons:

1. The -u indicates Basic Authorization username.
2. Most APIs reference the username and password formatted as username:password. There is a colon, which indicates that only a username is required for authentication.

To authorize this API in Parabola, fill in the fields below:

OAuth2.0

This method is an authorization protocol that allows users to sign into a platform using a third-party account. OAuth2.0 allows a user to selectively grant access for various applications they may want to use.

Authenticating via OAuth2.0 does require more time to configure. For more details on how to authorize using this method, read our guide Using OAuth2.0 in Parabola.

Expiring Access Token

Some APIs will require users to generate access tokens that have short expirations. Generally, any token that expires in less than 1 day is considered to be "short-lived" and may be using this type of authentication. This type of authentication in Parabola serves a grouping of related authentication styles that generally follow the same pattern.

One very specific type of authentication that is served by this option in Parabola is called OAuth2.0 Client Credentials. This differs from our standard OAuth2.0 support, which is built specifically for OAuth2.0 Authorization Code. Both Client Credentials and Authorization Code are part of the OAuth2.0 spec, but represent different Grant Types.

Authenticating with the Expiring Access Token option is more complex than options like Bearer Token, but less complex than OAuth2.0. For more details on how to use this option, read our guide Using Expiring Access Tokens in Parabola.

‍

Request Headers

A header is a piece of additional information to be sent with the request to an API. If an API requires additional headers, it is commonly noted in their documentation as -H.

Remember the authentication methods above? Some APIs list the authentication type to be sent as a header. Since Parabola has specific fields for authentication, those headers can typically be ignored.

Taking a look at Webflow's API, they show two headers are required.

The first -H header is linked to a key called Authorization. Parabola takes care of that. It does not need to be added as a header. The second -H header is linked to a key called accept-version. The value of the header is 1.0.0. This likely indicates which version of Webflow's API will be used.

Response JSON

APIs typically to structure data as a nested objects. This means data can exist inside data. To extract that data into separate columns and rows, use the Output section to select a top-level column.

For example, a character can exist as a data object. Inside the result object, additional data is included such as their name, date of birth, and location.

This API shows a data column linked result. To expand all of the data in the results object into neatly displayed columns, select results as the top-level column in the Output section.

If you only want to expand some of the columns, choose to keep specific columns and select the columns that you want to expand from the dropdown list.

Pagination

APIs return data in pages. This might not be noticeable for small requests, but larger request will not show all results. APIs return 1 page of results. To view the other pages, pagination settings must configured

Each API has different Pagination settings which can be searched in their documentation. The three main types of pagination are Page, Offset and Limit, and Cursor based pagination.

Page Based Pagination

APIs that use Page based pagination make it easy to request more pages. Documentation will refer to a specific parameter key for each request to return additional pages.

Intercom uses this style of pagination. Notice they reference the specific parameter key of page:

Parabola refers to this parameter as the Pagination Key. To request additional pages from Intercom's API, set the Pagination Key to page.

The Starting page is the first page to be requested. Most often, that value will be set to 0. For most pagination settings, 0 is the first page. The Increment by value is the number of pages to advance to. A value of 1 will fetch the next page. A value of 10 will fetch every tenth page.

Offset and Limit Based Pagination

APIs that use Offset and Limit based pagination require each request to limit the amount of items per page. Once that limit is reached, an offset is used to cycle through those pages.

Spotify refers to this type of pagination in their documentation:

To configure these pagination settings in Parabola, set the Pagination style to offset and limit.

The Starting Value is set to 0 to request the first page. The Increment by value is set to 10.  The request will first return page 0 and skip to page 10 .

The Limit Key is set to limit to tell the API to limit the amount of items. The Limit Value is set to 10 to define the number of items to return.

Cursor Based Pagination

Otherwise known as the bookmark of APIs, Cursor based pagination will mark a specific item with a cursor. To return additional pages, the API looks for a specific Cursor Key linked to a unique value or URL.

Squarespace uses cursor based pagination. Their documentation states that two Cursor Keys can be used. The first one is called nextPageCursor and has a unique value:

"nextPageCursor": "b342f5367c664d3c99aa56f44f95ab0a"

The second one is called nextPageUrl and has a URL value:

"nextPageUrl": "<https://api.squarespace.com/1.0/commerce/inventory?cursor=b342f5367c664d3c99aa56f44f95ab0a>"

To configure cursor based pagination using Squarespace, use these values in Parabola:

Replace the Cursor path in response with pagination.nextPageURL to use the URL as a value. The API should return the same results.

Rate Limiting

Imagine someone asking thousands of questions all at once. Before the first question can be answered thousands of new questions are coming in. That can become overwhelming.

Servers are no different. Making paginated API calls requires a separate request for each page. To avoid this, APIs have rate limiting rules to protect their servers from being overwhelmed with requests. Parabola can adjust the Max Requests per Minute to avoid rate limiting.

By default, this value is set to 60 requests per minute. That's 1 request per second. The Max Requests per Minute does not set how many requests are made per minute. Instead, it ensures that Parabola will not ask too many questions.

Lowering the requests will avoid rate limiting but will calculate data much slower. Parabola will stop calculating a flow after 60 minutes.

Max Pages to Fetch

To limit the amount of pages to fetch use this field to set the value. Lower values will return data much faster. Higher values will take longer return data.

The default value in Parabola is 5 pages. Just note, this value needs be larger than the expected number of pages to be returned. This prevents any data from being omitted.

If you are pulling a large amount of data and want to limit how much is being pulled in while building, you can set the step to pull a lower number of pages while editing the Flow than while running the Flow.

Encode URLs

URLs tend to break when there are special characters like spaces, accented characters, or even other URLs. Most often, this occurs when using {text merge} values to dynamically insert data into a URL.

Check the "Encode URLs" box to prevent the URL from breaking if special characters need to be passed.

Response type

By default, this step will parse the data sent back to Parabola from the API in the format indicated by the content-type header received. Sometimes, APIs will send a content-type that Parabola does not know how to parse. In these cases, adjust this setting from auto-detect to a different setting, to force the step to parse the data in a specific way.

Use the gzip option when the data is returned in a gzip format, but can be unzipped into csv, xml, or JSON data. If you enable gzip parsing, you must also specify a response type option.

Reading API Errors

Something not right? Check out this guide to learn more troubleshooting common API errors.

Input

This table shows the product information for new products to be added to a store. It shows common columns like "My Product Title", "My Product Description", "My Product Vendor", "My Product Tags".

These values can be used to create products in bulk via the Send to an API step.

Basic Settings

To use the Send to an API step, a Request Type, API Endpoint URL, and Authentication are required. Some APIs require Custom Headers while other APIs nest their data into a single cell that requires a Top Level Key to format into rows and columns.

Request Type

There are four ways to send data with an API using POST, PUT, PATCH, and DELETE requests. These methods are also known as verbs.

The POST verb is used to create new data. The DELETE verb is used to delete data.  The PUT verb is used to update exiting data, and the PATCH verb is used to modify a specific portion of the data.

Hey API, can you POST new data to the server?  The new data is in the JSON body.

API Endpoint URL

The API Endpoint URL is the specific location where data will be sent. Each API Endpoint URL belongs to a specific resource. A resource is the broader category to be targeted when sending data.

To create a new product in Shopify, use their Products resource. Their documentation specifies making a POST request to that resource using this Endpoint URL:

Your Shopify store domain will need to prepended to each Endpoint URL:

https://your-shop-name.myshopify.com/admin/api/2020-10/products.json

The request information is sent to the API in the JSON body of the request. The JSON body is a block that outlines the data that will be added.

Body

The body  of each request is where data that will be sent through the API is added. The body must be in raw JSON format using key:value pairs. The JSON below shows common attributes of a Shopify product.

{
 "product": {
   "title": "Baseball Hat",
   "body_html": "<strong>Awesome hat!</strong>",
   "vendor": "Parabola Cantina",
   "product_type": "Hat",
   "tags": [
     "Unisex",
     "Salsa",
     "Hat"
   ]
 }
}

Notice the title, body_html, vendor, product_type, and tags can be generated when sending this data to an API.

Since each product exists per row, {text merge} values can be used to dynamically pass the data in the JSON body.

This will create 3 products: White Tee, Pink Pants, and Sport Sunglasses with their respective product attributes.

Authentication

Most APIs require authentication to access their data. This is likely the first part of their documentation. Try searching for the word Authentication in their documentation. Below are the authentication types supported on Parabola:

The most common types of authentication are Bearer Tokens, Username/Password (also referred to as Basic), and OAuth 2.0. Parabola has integrated these authentication types directly into this step.

Bearer Token

This method requires you to send your API Key or API Token as a bearer token. Take a look at this example below:

The part that indicates it is a bearer token is this:

-H "Authorization: Bearer sk_test_WiyegCaE6iGr8eSucOHitqFF"

To add this specific token in Parabola, select Bearer Token from the Authorization menu and add sk_test_WiyegCaE6iGr8eSucOHitqFF as the value.

Username/Password (Basic)

This method is also referred to as Basic Authorization or simply Basic. Most often, the username and password used to sign into the service can be entered here.

However, some APIs require an API key to be used as a username, password, or both. If that's the case, Insert the API key into the respective field noted in the documentation.

The example below demonstrates how to connect to Stripe's API using the Basic Authorization method.

The Endpoint URL shows a DELETE request being made to a resource called customers.  The authorization type can be identified as Basic for two reasons:

1. The -u indicates Basic Authorizationusername.
2. Most APIs reference the username and password formatted as username:password. There is a colon : . This indicates that only a username is required for authentication.

To delete this customer using Parabola, fill in the fields below:

OAuth2.0

This method is an authorization protocol that allows users to sign into a platform using a third-party account. OAuth2.0 allows a user to selectively grant access for various applications they may want to use.

Authenticating via OAuth2.0 does require more time to configure. For more details on how to authorize using this method, read our guide Using OAuth2.0 in Parabola.

Expiring Access Token

Some APIs will require users to generate access tokens that have short expirations. Generally, any token that expires in less than 1 day is considered to be "short-lived" and may be using this type of authentication. This type of authentication in Parabola serves a grouping of related authentication styles that generally follow the same pattern.

One very specific type of authentication that is served by this option in Parabola is called OAuth2.0 Client Credentials. This differs from our standard OAuth2.0 support, which is built specifically for OAuth2.0 Authorization Code. Both Client Credentials and Authorization Code are part of the OAuth2.0 spec, but represent different Grant Types.

Authenticating with the Expiring Access Token option is more complex than options like Bearer Token, but less complex than OAuth2.0. For more details on how to use this option, read our guide Using Expiring Access Tokens in Parabola.

‍

Custom Headers

A header is a piece of additional information to be sent with the request to an API. If an API requires additional headers, it is commonly noted in their documentation as -H.

Remember the authentication methods above? Some APIs list the authentication type to be sent as a header. Since Parabola has specific fields for authentication, those headers can typically be ignored.

Taking a look at Webflow's API, they show two headers are required.

The first -H header is linked to a key called Authorization. Parabola takes care of that. It does not need to be added as a header. The second -H header is linked to a key called accept-version. The value of the header is 1.0.0. This likely indicates which version of Webflow's API will be used.

Advanced Settings

Encode URLs

URLs tend to break when there are special characters like spaces, accented characters, or even other URLs. Most often, this occurs when using {text merge} values to dynamically insert data into a URL.

Check the "Encode URLs" box to prevent the URL from breaking if special characters need to be passed.

Reading API Errors

Check out this guide to learn more troubleshooting common API errors.

Input/output

Our input data has two columns: "data.id" and "data.employee_name".

Our output data, after using this step, has three new columns appended to it: "api.status", "api.data.id", and "api.data.employee_name". This data was appended to each row that made the call to the API.

Custom settings

First, decide if your data needs a GET or POST operation, or the less common PUT or PATCH, and select it in the Type dropdown. A GET operation is the most common way to request data from an API. A POST is another way to request data, though it is more commonly used to make changes, like adding a new user to a table. PUT and PATCH make updates to data, and sometimes return a new value that can be useful.

Insert your API endpoint URL in the text field.

Sending a body in your API request

• A GET cannot send a body in its request. A POST can send a Body in its request. In Parabola, the Body of the request will always be sent in JSON.
• Simple JSON looks like this:

{ "key1":"value1", "key2":"value2", "key3":"value3" }

Using merge tags

• Merge tags can be added to the API Endpoint URL or the Body of a request. For example, if you have a column named "data.id", you could use it in the API Endpoint URL by including {data.id} in it. Your URL would look like this:

http://third-party-api-goes-here.com/users/{data.id}

• Similarly, you can add merge tags to the body.

{
"key1": "{data.id}",
"key2": "{data.employee_name}",
"key3": "{Type}"
}

• For this GET example, your API endpoint URL will require an ID or some sort of unique identifier required by the API to match your data request with the data available. Append that ID column to your API endpoint URL. In this case, we use {data.id}.
• Important Note: If the column referenced in the API endpoint URL is named "api", the enrichment step will remove the column after the calculation. Use the Edit Columns step to change the column name to anything besides "api", such as "api.id".

‍

Authentication

Most APIs require authentication to access their data. This is likely the first part of their documentation. Try searching for the word "authentication" in their documentation.

Here are the authentication types available in Parabola:

The most common types of authentication are 'Bearer Token', 'Username/Password' (also referred to as Basic), and 'OAuth2.0'. Parabola has integrated these authentication types directly into this step.

Bearer Token

This method requires you to send your API key or API token as a bearer token. Take a look at this example below:

The part that indicates it is a bearer token is this:

-H "Authorization: Bearer sk_test_WiyegCaE6iGr8eSucOHitqFF"

To add this specific token in Parabola, select 'Bearer Token' from the 'Authorization' menu and add "sk_test_WiyegCaE6iGr8eSucOHitqFF" as the value.

Username and Password (Basic)

This method is also referred to as "basic authorization" or simply "basic". Most often, the username and password used to sign into the service can be entered here.

However, some APIs require an API key to be used as a username, password, or both. If that's the case, insert the API key into the respective field noted in the documentation.

The example below demonstrates how to connect to Stripe's API using the basic authorization method.

The endpoint URL shows a request being made to a resource called customers.  The authorization type can be identified as basic for two reasons:

1. The -u indicates a username.
2. Most APIs reference the username and password formatted as username:password. Here, there is a colon with no string following, indicating that only a username is required for authentication.

To authorize this API in Parabola, fill in the fields below:

OAuth2.0

This method is an authorization protocol that allows users to sign into a platform using a third-party account. OAuth2.0 allows a user to selectively grant access for various applications they may want to use.

Authenticating via OAuth2.0 does require more time to configure. For more details on how to authorize using this method, read our guide Using OAuth2.0 in Parabola.

Expiring Access Token

Some APIs will require users to generate access tokens that have short expirations. Generally, any token that expires in less than 1 day is considered to be "short-lived" and may be using this type of authentication. This type of authentication in Parabola serves a grouping of related authentication styles that generally follow the same pattern.

One very specific type of authentication that is served by this option in Parabola is called "OAuth2.0 Client Credentials". This differs from our standard OAuth2.0 support, which is built specifically for "OAuth2.0 Authorization Code". Both methods are part of the OAuth2.0 spec, but represent different grant types.

Authenticating with an expiring access token is more complex than using a bearer token, but less complex than OAuth2.0. For more details on how to use this option, read our guide Using Expiring Access Tokens in Parabola.

‍

Enabling Error Handling

In the Enrich with an API step and the Send to an API step, enable Error Handling to allow your API steps to pass through data even if one or more API requests fail. Modifying this setting will add new error handling columns to your dataset reporting on the status of those API calls

By default, this section will show that the step will stop running when 1 row fails. This has always been the standard behavior of our API steps. Remember, each row of data is a separate API call. With this default setting enabled, you will never see any error handling columns.

Update that setting, and you will see that new columns are set to be added to your data. These new columns are:

• ‍API Success Status
• API Error Code
• API Error Message

API Success Status will print out a true or false value to show if that row's API call succeeded or failed.

API Error Code will have an error code for that row if the API call failed, and will be blank if the API call succeeded.

API Error Message will display the error message associated with any API call that failed, if the API did in fact send us back a message.

With the exception of the default settings, these columns will still be included even if every row succeeded. In that case, you will see the API Success Status column with all true values, and the other two columns as all blank values.

Using the error handling settings

It is smart to set a threshold where the step will still fail if enough rows have failed. Usually, if enough rows fail to make successful API calls, there may be a problem with your step settings, the data you are merging into those calls, or the API itself. In these cases, it is a good idea to ensure that the step can fully stop without needing to run through every row.

Choose to stop running this step if either a static number of rows fail, or if a percentage of rows fail.

You must choose a number greater than 0.

When using a percentage, Parabola will always round up to the next row if the percentage of the current set of rows results in a partial row.

Prevent the step from ever stopping

In rare cases, you may want to ensure that your step never stops running, even if every row results in a failed API call. In that case, set your error handling threshold to any number greater than 100%, such as 101% or 200%.

What to do with these new error handling columns

Once you have enabled this setting, use these new columns to create a branch to deal with errors. The most common use case will be to use a Filter Rows step to filter down to just the rows that have failed, and then send those to a Google Sheet for someone to check on and make adjustments accordingly.

‍

Error handling in the Live flow Run logs

If you have a flow that is utilizing these error handling columns, the run logs on the live view of the flow will not indicate if any rows were recorded as failed. The run logs will only show a failure if the step was forced to stop by exceeding the threshold of acceptable errors. It is highly advisable that you set up your flow to create a CSV or a Google Sheet of these errors so that you have a record of them from each run.

‍

Errors and explanations without error codes

The Pull from an API and Send to an API steps can return errors that do not have a response code. These are usually errors that happened within Parabola, instead of errors that were returned by the API.

Common Parabola explanations and errors

The URL returned empty or blank data.

You will see this explanation when your API has either returned data that is not in a format Parabola can process, when it is in a corrupted format, when the response was completely blank or was an empty table.

Usually this means that you are not requesting the proper resource, you are using an API that does not return JSON, XML or CSV data, or your endpoint simply has no data to return.

‍

It appears this data might not be fully expanded. If so, try using Top Level Keys or the JSON Flattener step to format your data.

This explanation will show when your data has come back from your API and has the potential to be expanded into a more usable table. You can add a Top Level Key if that option is available in the Pull from an API step, or you can use an Expand with JSON step.

‍

Your JSON is not Valid! Try using a JSON linter to make sure you have the right syntax.

This message shows when there is an invalid syntax in your JSON or GraphQL. The error will let you know the request that caused the error, which row it is on, and a small message about where to look for the error.

‍

Max requests (#) hit

This explanation shows up when the API step has used the pagination settings and has made it all the way to the max request number. Many times this may mean your API has more pages of data for the request, but the paging was stopped. Try increasing your Max Requests field.

‍

The object failed to calculate. Please try again.

or

There was a calculation error in <step>

or

The step failed to calculate. Our team is aware and looking into it.

These errors can be due to a few internal issues within Parabola. The step may have taken more than 60 minutes to complete and was terminated. The step may have used too much memory due to the data size. The step may have encountered an unknown error and failed.

We monitor these errors and fix their underlying issues when they arise. If you see these a lot, please reach out to us if we have not reached out to you.

‍

URL refers to a column name that does not exist

This error will only show up on the Enrich with an API step, and indicates that your endpoint URL is trying to reference a column in the data that does not exist. This step uses {curly braces} to indicate a column to merge into the requests, so anything within {curly braces} should be a column name.

If your API uses {curly braces} in its request syntax, please reach out to us and we can show you how to work around that.

Common 500 series errors

Any error that comes back with a code beginning with a "5" are errors that happened after Parabola made the request to the service, but before Parabola received the response.

For example, if you send a letter through the mail, and if physical mail had error codes, you would see a 502 error if the mail delivery truck ran out of gas. You could see a 503 error if the mailbox was broken, and if you saw a 504 error, it would mean that the delivery took too long so the mail carrier gave up.

Resolving 500 series errors

In general, these errors should be temporary, or one-off. Within Parabola, click the refresh icon next to the name of the API step that you are using to send the request again, and the error will likely resolve itself.

If you are continuously getting 500 series errors, it usually indicates that something is down, such as the hosting service for the API, or another piece of network technology.

500 series errors are produced between Parabola and the API. Your best course of action to resolve them is to refresh the step and try the request again. The API did not process your request as expected.

Common 400 series errors

The 400 series of error codes indicates that the request from Parabola made it to your API, but the API did not like the request for some reason. The error code can show you how to adjust your settings in Parabola or in your API to resolve the error.

Resolving 400 series errors

Each 400 series error requires a different approach to fix it. Fixing these errors may take a few tries and can be nuanced. Your best ally in hunting down the issue is the documentation provided by the API.

Error 400: Bad Request

This error indicates that the API received your request, and it was able to read it, but something in the request is syntactically incorrect, such as a spelling error, or missing headers.

Make sure that your endpoint URL in the Parabola API step settings is spelled correctly and does not have any spaces or hidden characters (such as line breaks) in it.

If you are sending query parameters, make sure they are exactly like the doc specifies. A good practice is to copy and paste any text needed in your settings directly from their documentation to avoid mistyping them.

Error 401: Unauthorized

This error shows up when you have either not passed any authentication to the API, or have passed authentication that has not succeeded. Usually, if your syntax is incorrect, you will get a 400. Knowing that, a 401 means that your request is probably going to work, you just need to prove to the API who you are.

API docs are useful in solving a 401, because they outline the exact way to pass in authentication. Check the docs and make sure that the credentials you are sending via the API step in Parabola are correct. A 401 could mean that you do not have permission to access this resource. You may need to adjust your account permissions in the service that has the API.

Error 402: Payment Required

You need to go to the website of the API that you are trying to access and update your billing or resolve any outstanding invoices there.

Error 403: Forbidden

Check your API docs as to why they would send a 403. Many API docs have section about what error codes mean for their API specifically. You may not have access to the requested resource.

Error 404: Not Found

The resource you requested does not exist, so check your API URL for any incorrect spellings, and make sure that the API endpoint you are trying to hit is defined in their documentation.

Error 405: Method Not Allowed

If you are using a Pull from an API or an Enrich with an API step, you are using the GET method. Your resource may require something like a POST, which can only be done with an API Export. Similarly, if you are using a POST, but it should be a PUT, you may get this error.

Check your APIs documentation to ensure that the resource you are requesting is compatible with the verb that you are using to make the request.

Error 422: Unprocessable Entity

You need to check your request for errors in what you are asking the API for. Check your API docs to ensure that the request is asking for its resource in exactly the correct way. This error code usually indicates that your request does not make sense to the API.

Error 429: Too Many Requests

This is a rate limiting error, sent back when Parabola has requested a resource too many times or has made sequenced calls too quickly.

In the API steps, there is a setting for the Max Requests to be sent each minute. You can adjust this number to reflect the limit that the API defines in its docs. Each API is different, so look for a section called Rate Limits or something similar.

400 series errors indicate issues with your requestMost likely, you will need to check your API docs and adjust anything in your settings in Parabola for this API step to ensure you are following the rules of the API defined in the docs.

Appendix of HTTP Errors

400 Bad Request

The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing).

401 Unauthorized

Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. 401 semantically means "unauthenticated", i.e. the user does not have the necessary credentials.Note: Some sites incorrectly issue HTTP 401 when an IP address is banned from the website (usually the website domain) and that specific address is refused permission to access a website.

402 Payment Required

Google Developers API uses this status if a particular developer has exceeded the daily limit on requests. Sipgate uses this code if an account does not have sufficient funds to start a call. Shopify uses this code when the store has not paid their fees and is temporarily disabled.

403 Forbidden

The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort.

404 Not Found

The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.

405 Method Not Allowed

A request method is not supported for the requested resource; for example, a GET request on a form that requires data to be presented via POST, or a PUT request on a read-only resource.

‍406 Not Acceptable

The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.

407 Proxy Authentication Required

The client must first authenticate itself with the proxy.

408 Request Timeout

The server timed out waiting for the request. According to HTTP specifications: "The client did not produce a request within the time that the server was prepared to wait. The client MAY repeat the request without modifications at any later time."

409 Conflict

Indicates that the request could not be processed because of conflict in the current state of the resource, such as an edit conflict between multiple simultaneous updates.

410 Gone

Indicates that the resource requested is no longer available and will not be available again. This should be used when a resource has been intentionally removed and the resource should be purged. Upon receiving a 410 status code, the client should not request the resource in the future. Clients such as search engines should remove the resource from their indices. Most use cases do not require clients and search engines to purge the resource, and a "404 Not Found" may be used instead.

411 Length Required

The request did not specify the length of its content, which is required by the requested resource.

412 Precondition Failed

The server does not meet one of the preconditions that the requester put on the request.

413 Payload Too Large

The request is larger than the server is willing or able to process. Previously called "Request Entity Too Large".

414 URI Too Long

The URI provided was too long for the server to process. Often the result of too much data being encoded as a query-string of a GET request, in which case it should be converted to a POST request.

415 Unsupported Media Type

The request entity has a media type which the server or resource does not support. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format.

416 Range Not Satisfiable

The client has asked for a portion of the file (byte serving), but the server cannot supply that portion. For example, if the client asked for a part of the file that lies beyond the end of the file.

417 Expectation Failed

The server cannot meet the requirements of the Expect request-header field.

418 I'm a teapot

This code was defined in 1998 as one of the traditional IETF April Fools' jokes, in RFC 2324, Hyper Text Coffee Pot Control Protocol, and is not expected to be implemented by actual HTTP servers. The RFC specifies this code should be returned by teapots requested to brew coffee.

421 Misdirected Request

The request was directed at a server that is not able to produce a response (for example because of connection reuse).

422 Unprocessable Entity

The request was well-formed but was unable to be followed due to semantic errors.

423 Locked

The resource that is being accessed is locked.

424 Failed Dependency

The request failed because it depended on another request and that request failed (e.g., a PROPPATCH).

426 Upgrade Required

The client should switch to a different protocol such as TLS/1.0, given in the Upgrade header field.

428 Precondition Required

The origin server requires the request to be conditional. Intended to prevent the 'lost update' problem, where a client GETs a resource's state, modifies it, and PUTs it back to the server, when meanwhile a third party has modified the state on the server, leading to a conflict.

429 Too Many Requests

The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes.

431 Request Header Fields Too Large

The server is unwilling to process the request because either an individual header field, or all the header fields collectively, are too large.

451 Unavailable For Legal Reasons

A server operator has received a legal demand to deny access to a resource or to a set of resources that includes the requested resource. The code 451 was chosen as a reference to the novel Fahrenheit 451.

500 Internal Server Error

A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

501 Not Implemented

The server either does not recognize the request method, or it lacks the ability to fulfill the request. Usually this implies future availability (e.g., a new feature of a web-service API).

502 Bad Gateway

The server was acting as a gateway or proxy and received an invalid response from the upstream server.

503 Service Unavailable

The server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.

504 Gateway Timeout

‍The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.

505 HTTP Version Not Supported

The server does not support the HTTP protocol version used in the request.

506 Variant Also Negotiates

Transparent content negotiation for the request results in a circular reference.

507 Insufficient Storage

The server is unable to store the representation needed to complete the request.

508 Loop Detected

The server detected an infinite loop while processing the request (sent instead of 208 Already Reported).

510 Not Extended

Further extensions to the request are required for the server to fulfill it.

511 Network Authentication Required

The client needs to authenticate to gain network access. Intended for use by intercepting proxies used to control access to the network (e.g., "captive portals" used to require agreement to Terms of Service before granting full Internet access via a Wi-Fi hotspot).

Authorization

All OAuth connections will require you to register an application with the service. Reading their API documentation will provide instructions on how to connect using OAuth 2.0.

‍

Important note: Parabola can generally support OAuth 2.0 when the request requires grant_type=authorization_code. The other most common grant_type is client_credentials, and unfortunately Parabola cannot currently support that grant_type.

Redirect URL

The first step is to register your application with the service you want to access. They require you to provide a Callback URL, Return URI, or Redirect URL. These terms are referring to the same thing—a specific URL where the service will send Parabola an access token for your account.

Provide the service with the following Redirect URL:

https://parabola.io/api/steps/generic_api/callback

‍

After registering your application, you will receive at least two credentials. The first credential is the client_id. Think of this as a username. The second credential is a client_secret. This is a password. Services may refer to these credentials differently. Use your best judgement when identifying the client_id and client_secret.

The image below shows the Client ID and Client Secret on the Spotify developer dashboard.

Authorization Request URL

The next step is to construct an Authorization Request URL in Parabola. This URL consists of a base URL and URL parameters. The following is Spotify's base URL:

https://accounts.spotify.com/authorize

It also requires a client_id, response_type, and redirect_uri as parameters.

‍

Edit URL Parameters

Adding URL parameters can be manually typed in. However, adding in parameters using the Edit URL Parameters section will help auto construct the URL.

Access Token

The next step is to to request an access token to grant Parabola permission to access your service's data. All requests must be sent to an Access Token Request URL, or more simply, a token URL.

‍

Access Token Request URL

To receive an access token, a request must be sent to the token URL with Access Token Request Body parameters. Look for a URL that ends in /token.

Access Token Method

Most likely, a POST request will be made to the token URL. If the service does require a GET request, the Access Token Request Body parameters must be manually typed into the URL.

Spotify's token URL is listed as

https://accounts.spotify.com/api/token

‍

‍

Access Token Request Body

We can add the Access Token Request Body to our request by using pairs. The above image shows Spotify requires a grant_type, code, and redirect_uri as body parameters.

Parabola automatically sends code as a parameter. Do not add that as a parameter when configuring this step.

Advanced Options

Spotify also requires a header parameter. Add a Custom Header and add "Authorization" as the Header Key. The Header Value is

Basic: your_client_id:your_client_secret.

Swap out your actual client_id and client_secret separated by a colon :

‍

Spotify requires you to base64 encode your client_id and your client_secret. To do this, copy this portion from your Header Value:

your_client_id:your_client_secret

Paste it into this website to base64 encode those credentials.

Refresh Token

Since the access tokens will expire, Parabola will need to request a refresh token to stay authorized with your service. These requests must be sent to an Refresh Token Request URL, or more simply, a refresh URL.

Refresh Token Request URL

To receive a refresh token, a request must be sent to the refresh URL  with Refresh Token Request Body parameters. In many cases, this base URL is identical to the Access Token Request URL and ends with /token.

Spotify's refresh URL is also

https://accounts.spotify.com/api/token

‍

Refresh Token Method

Again, a POST request will be made to the refresh URL. If the service does require a GET request, the Refresh Token Request Body parameters must be manually typed into the URL.

Refresh Token Request Body

We can add the Refresh Token Request Body to our request by using key:value pairs.  The  image below shows Spotify requires a grant_type and refresh_token as body parameters.

‍

Advanced Options

Add a Custom Header if your service requires them. Spotify mentions adding Authorization as the Header Key again. The Header Value is

Basic: your_client_id:your_client_secret

Authorize

Click "Authorize" to grant Parabola access to your service. If successful, you will be returned to your flow and see that it is ready for use.

Now that you are authentication, make a request to the Endpoint URL as you normally would by adding body parameters or custom headers when necessary. The API should now return data to Parabola.

Still having trouble?

If you encounter an error, try reconfiguring your settings. To adjust the form, click Edit accounts at the top of the result view, then click edit. Find the authorization that you made, and click the pencil icon to bring up your settings.

When to use this authentication method

If you have an API that mentions the need to fetch a new token because the access tokens expire quickly, then this method may be useful for you. Sometimes, you may see this referred to as a JWT (Javascript Web Token) in the API docs

Also, if the API docs that you are looking at specify that they use OAuth2.0 Client Credentials grant type, then you should use this authentication method.

For example, Spotify has docs for using Client Credentials with their API:

‍

Another example is the ShipHero API docs, which show that they use JWTs for authentication:

Filling out the Expiring Access Token form in your flow

The Expiring Access Token auth form in Parabola has a few fields to fill out:

1. Authentication Token Request URL
2. Body Request Parameters
3. Request Headers
4. Response Access Token field
5. Header Key for using Access Token
6. Header Value for using Access Token

Authentication Request URL

First, let's look at the authentication request URL and optional authentication request parameters. Any API that uses this auth method will have a URL that you need to send a POST request to in order to get the access token. Put that URL in this field.

In the example from the ShipHero docs, they expect us to send a POST to https://public-api.shiphero.com/auth/token to get the access token.

Body Request Parameters

Request parameters may be required by the API. The docs will almost always call these some sort of parameter - body parameters or request parameters. If your API docs look like the ShipHero API docs, then it may be unlabeled:

As you can see, we need to send them a username and password. This request is written in cURL, and that means we know that the parts that follow "-d" or "--data" will be the parameters. So, in Parabola, we can enter this as:

These parameters will be encoded and sent to the API according to the content-type header that you set further down in the form.

Custom Headers

By default, this form will show you two headers - Content-Type and Accept. Both are set to application/json. You may need to change the Content-Type header to application/x-www-form-urlencoded if your API requires that. Notice how the Spotify API docs require that change:

You can always add more headers if needed.

The most common header you may need to add is Authorization. Notice how the screenshot above from Spotify also needs that header. Usually in this context, it will be used to send some additional information, like the client_id and client_secret.

If your API, like Spotify, says that you ned to take your client_id and client_secret (or anything) and Base 64 encode it, then you will need to do the encoding outside of Parabola. There are many websites that will Base 64 encode for you, so search for and choose one.

Let's say that your client_id is bob and your client_secret is Green123. Combine those so they look like this: bob:Green123 and pass them through a Base 64 encoding service. In this example, that will be converted into: Ym9iOkdyZWVuMTIz

Now, combine that with the word "Basic" to get Basic Ym9iOkdyZWVuMTIz and put that as the value for the Authorization header:

Response Access Token field

Every setting up to this point has been in service of getting an access token from an API.

Now, this field informs Parabola how to find the token within the response.

It is very common for APIs to send the token that you need to authenticate with back in a key called access_token. But if your API calls it something else, you can adjust that here.

For example, the ShipHero API sends back the token in a key called access_token:

If their docs instead called it "awesome_token", you could use this field to tell Parabola to look for awesome_token and use that for authentication.

Once Parabola has the token, by default, it will be sent in your API requests as a bearer token. If the API that you’re working with requires a custom header to be used instead of a bearer token, you can use the Advanced Settings. 

Advanced Settings (Pass Access Token in Custom Header)

Every time your Parabola Flow runs, we grab a fresh token that is then inserted into your API request. By default, Parabola will use this access token specifically as a bearer token in API requests, so this works well when the API you are trying to connect to accepts bearer-token-based authentication (which is most common).

There are also instances where the API you’re working with requires tokens to be passed as a custom header, such as AUTH-TOKEN. For these types of APIs, you can use the Header Key for using Access Token in the Advanced Settings option to specify a header key.

The Header Value for using Access Token field will always include the string {token} – in your live API call, {token} is replaced by whatever was found by the Response Access Token Field. 

In the above example, the API returned the Access Token in the access_token key, then we included that token in our subsequent request using the AUTH-TOKEN header.

Still having trouble?

If you encounter an error, try reconfiguring your settings. To adjust the form, click Choose accounts at the top of the result view, then click edit. Find the authorization that you made, and click the pencil icon to bring up your settings.

Also, ensure that you’ve selected “Expiring Access Token” in the “Authentication” dropdown list. 

‍

‍