View Navigation
Integrations   ->

Introduction to APIs

The first time interacting with an API can feel daunting. Each API is unique and requires different settings, but are generally standardized to make understand and connecting to an API accessible.

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.

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 make a request to a specific resource by specifying the exact data it needs using a query parameter wrapped in curly brackets {}. The query parameter is added to the end of the Endpoint URL.

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 URL. This shows 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.

https://assets.website-files.com/5d9bdcad630fbe7a7468a9d8/5df043083024f8acf53e7729_Screen Shot 2019-12-10 at 5.14.37 PM.png

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.

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:

https://assets.website-files.com/5d9bdcad630fbe7a7468a9d8/5df049f8fc0b1a217704f242_Screen Shot 2019-12-10 at 5.44.15 PM.png

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.

Recipes

Integrations   ->

Pull from an API

The Pull from an API step sends a request to an API to return specific data. In order for Parabola to receive this data, it must be returned in a CSV, JSON, or XML format. This step allows Parabola to connect to a third-party to import data from another service, platform, or account.

Basic Settings

To use the Pull from an API step the 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 two ways to request data from an API using a GET request or 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 determined where to request data from or where to send new data to. Below is an example of an API Endpoint URL.

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.

https://assets.website-files.com/5d9bdcad630fbe7a7468a9d8/5df043083024f8acf53e7729_Screen Shot 2019-12-10 at 5.14.37 PM.png

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 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 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.

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.

Nested Keys

APIs typically to structure data as a nested objects. This means data can exists inside data. To extract that data into separate columns and rows, use a Top Level Key.

For example, a customer can exist as a data object. Inside the customer object, additional data is included such as their name, shipping address, and email address.

This API shows a data column linked customer. To expand that data into neatly displayed columns, select data as the top level key.

Advanced Settings

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 Pagination Start Value 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 Pagination 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.

The Max Pages to Fetch limits the total amount of pages to return. Setting that value to 5 will fetch the first 5 pages defined by your Pagination Start Value and Incrementation Value.

This API call will return pages 0-4.

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 Key to offset.

The Pagination Start Value is set to 0 to request the first page. The Increment Pagination 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 Size is set to 10 to define the number of items to return.

The Max Pages to Fetch limits the total amount of pages to return. Setting that value to 5 will fetch the first 5 pages defined by your Pagination Start Value and Incrementation Value.

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 Key with pagination.nextPageURL to use the URL as a value. The API should return the same results.

In the Number of Rows to Add field, enter the total number of new rows to add to a table.

Max Requests per Minute

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 require 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.

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

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

Integrations   ->

Send to an API

The  Send to an API step sends a request to an API to export specific data.  Data must be sent through the API using JSON formatted in the body of the request. This step can send data only when a flow is published.

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 bulk create products using 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: Baseball Hat, Classic T-Shirt, and Logo Mug 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.

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.

Integrations   ->

Enrich with an API

Use the Enrich with an API step to make API requests using a list of data, enriching each row with data from an external API endpoint.

Input/output

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

My output data, after using the Enrich with an API step, has three new columns appended to it: "api.status", "api.data.id", "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 requires a GET or POST operation 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, such as adding a new user to a table.

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}.

Authentication

Most APIs require some sort of authentication to access their data. This should make sense, as you need to login to view your account and data inside of most apps.

API docs will usually have a section on this. Try searching for the word Authentication in the docs pages.

Parabola's authentication settings are the same across all of our API steps: Pull from an API step, Send to an API step, Enrich with an API step. Head to the API integration doc for more information on authenticating your API steps on Parabola.

Recipes

Integrations   ->

Common API Errors

Sometimes, an API cannot parse the data because of how you structured the request. When something goes wrong, the API will return a brief description outlining the error details.

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 a Expand with JSON step.

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).

Recipes

Integrations   ->

Using OAuth 2.0 in Parabola

OAuth 2.0 is an authentication type that grants limited access to another application using a third-party user account. Most people have interacted with OAuth 2.0 by signing into service using a Google or Facebook account.

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.

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.

Recipes

Try Parabola for free