API Connector
Application Programming Interface or API is an important data source that Acho can support. You can reference the following steps to build a connection with your API. If you need any helps to set up the API connection, please contact us.
1. Go to the Resources page and click the Add Resource button.
2. Select API.
3. Configure your your API. You can click the Test button to see whether to get the response normally. (Note: please see here to learn how to set up each field)
5. Click Connect. You will see a icon next to your API resource. It may take a few minutes to several hours depending on the data size. Once your data is ready, you will receive a notification email.
The displayed name of your API resource on the resource page.
It's the API URL path to connect with your apps or integrations. Acho supports any APIs that follow REST conventions. For example,
https://api.unibit.ai/v2/stock/historical?tickers=AAPL&accessKey=demo&dataType=json.API parameters are the optional key-value pairs used for determining details of your API. Generally, you can specify them after the question mark (
?) in your API. If there are multiple parameters, they will be appended together with an & sign. Take the following API as an example. There are three parameters:- tickers = AAPL
- accessKey = demo
- dataType = json
Parameters example
Acho supports two ways to specify your parameters.
You can define parameters inside the URL field directly. Remember to specify them after a question mark and use "&" to concatenate all parameters. However, if you use {} to specify an embedded parameter, "{}" , in your URL, you can only specify other parameters in the Parameters tab.
API URL Field
Another way is to list each key and value in the Parameters tab as shown below.
Parameters Tab
Acho support three types of authorization to validate API access.
- None default): If your API doesn't require authorization, you can select
None. - Basic Auth: It requires providing a username and a password.
- Bearer Token: It requires providing Bearer Token.
If your API authorization requires an API key or an access token and needs to define it as a part of query parameters, please choose
None in the authorization type and specify the API key in Headers or Parameters. API headers are like an extra source of information for each API call you make. Their job is to represent the meta-data associated with an API request and response. Examples of headers you may encounter are credentials for HTTP authentication, content type, or cache control.
Headers example
Like parameters, headers are key-value pairs. You can define one or more headers. Some headers are required but some are optional. Generally, you can find the list of available headers in your API documentation.
Data format is the output scheme of the data from your API.
JSON (JavaScript Object Notation) is a lightweight data-interchange format that store and transmit data objects consisting of key–value pairs and arrays. Most of the APIs return data in a JSON format. The following API example is to return data in JSON format.
https://api.unibit.ai/v2/stock/historical?tickers=AAPL&accessKey=demo&dataType=json
If you pass it into the URL field and click Test, you can get the following response.
API data in the JSON format
If your data is stored in a nested JSON object, you can define the path to tell the system where to access it. In the above example, the raw data is stored inside the "AAPL" key and the
AAPL key is stored in the result_data key. To access the raw data, the path can be defined as result_data.AAPL.JSON - JSON Path Example
A CSV file refers to a "comma-separated values" file uses a comma to separate values. If your API returns a downloadable CSV file, you have to specify
CSV in Data Format. Thus, the system will parse your data correctly. Here is an example API: https://api.unibit.ai/v2/stock/historical?tickers=AAPL&accessKey=demo&dataType=csv
XML is a markup language similar to HTML, but without predefined tags to use. Here is an XML response example:
https://stageappsp.smashfly.com/contactmanagerservice/v2/ContactManagerRestService.svc/help/operations/SaveContact
You can get the response as shown below
XML - JSON Path
Acho turns the XML response into a JSON format so that you can define JSON path to access the specific data you need easier. For example, if you only need
body data within the html key, just specify html.body in JSON Path. XML - JSON Path example
Some APIs may not allow you to retrieve all records in a single request. Turning on Multiple Requests allows you to retrieve data multiple times based on a specific parameter key. Multiple Requests can address the following issues:
- Your API has a maximum number record limit to retrieve in each request.
- Your API only allows you to retrieve a small amount of data based on a specific parameter. For example, you can only retrieve data related a specific customer_id at a time.
It's to retrieve data depending on the row number. This method splits data into several batches based on the row number and only retrieve one batch of the data at a time until there is no data that can be retrieved.
For example, if the original dataset has 3000 records and we set up retrieving 1000 rows at a time, the system will call the API three times to get all data.
The Mechanism of Iteration Requests
Options:
- Request Limit: The maximum number of records to retrieve at a time. Most of the APIs call this parameter as
limit. (Note: please make sure your API has this parameter) - Start Parameter Key: A parameter to decide where to start to retrieve data. Most of the APIs call this parameter as
start. (Note: please make sure your API has this parameter)
It's to retrieve data depending on a specific field rather than the row number.
- Request Limit: The maximum number of records to retrieve at a time. Generally, the key to the API is called
limit. - Start Parameter Key: It's a parameter used for specifying where to start to return rows. This should be the last value of a given field retrieved previously. Basically, the
Parameter Keyis dependent onField Name. - Field Name: the field that is used for deciding the order of
Take the above as an example. In this case, the API will retrieve 1000 records at a time and the order is based on the
transaction_id. start_after_transaction_id records the last transaction id in the last request, and thus the API will start from the transaction_id after this value in the next request. For example, if the 1000th transaction_id is "trans1000", then the second request will start from the row which transaction_id is after "trans1000". The requests won't end until all data are retrieved.
If your URL has an embedded parameter inside the curly bracket,
{}, you have to specify the loop method at the same time. You can determine an array of values from a column in one of the project table. Then, the system will loop through the array and replace the value within the bracket to request data. - Loop Parameter Key: The key name inside the curly brackets, {}, in your API URL.
- Values to Loop: The array of values to loop inside the brackets. The values should be referred from a column in your project table.
If your API data is real-time, you can turn on API Update to retrieve data at a certain time interval. There are three options in the settings of API Update.
- Update Method: refers to how to deal with the new data points and the current data points.
- Replace: Every time Acho requests data through the API, it will replace the current dataset with the latest dataset entirely.
- Incremental: Every time Acho requests data through the API, it will append the new data points to the current dataset. This method may generate duplicate data points.
- Sync Frequency: refers to how often Acho should retrieve data through the API. There are three options that you can choose from:
- Intraday: update the table every specific time interval within a day. The minimum time interval is 15 minutes.
- Daily: update the table at a specific time (such as 6 a.m.) every day.
- Custom: you can define the scheduler in a more flexible way.
Acho supports setting up dynamic dates ranges without changing parameters or URLs manually. Currently, there are four dynamic date expressions on Acho:
{year}: refers to the current year in UTC. The year is expressed in 4 digits, such as 2021.{month}: refers to the current month in UTC. The month is expressed in 2 digits, such as 08.{day}: refers to the current day in UTC. The month is expressed in 2 digits, such as 23.{yesterday-full-date}: refers to yesterday's date in the format of "yyyy-mm-dd", such as 2021-08-22.{yesterday_full_date}: refers to yesterday's date in the format of "yyyy_mm_dd", such as 2021_08_22.
You can feel free to put the expression in URLs or Parameters. Here are the examples.
- Change the month in the API URL to this month automatically.
http://api.example.com/xxx/{year}-{month}
- Change the date in the API URL to today's date.
http://api.example.com/xxx/{year}-{month}-{day}
- Change the date in the API URL to yesterday's date.
http://api.example.com/xxx/{yesterday-full-date}
If there are two parameter keys, startDate and endDate, to define the date range in your API, then you can use the dynamic date expression in both parameters. Here are some examples of how to use dynamic date expressions in Parameters.
- Retrieve data from 2021-01-01 to the current date
- Retrieve data from 2021-01-01 to yesterday
- Only retrieve today's data
- Only retrieve yesterday's data
- Only retrieve this month's data
Last modified 7mo ago