Acho
ProductsPricingGlossary Launch Acho
Search…
⌃K
Links

API Connector

Import data from API

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

Configure your API connection

1. Resource Name

The displayed name of your API resource on the resource page.

2. URL

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.

3. Parameters

API parameters are the optional key-value pairs used for determining the 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.

1. Specify parameters in your URL

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

2. Specify parameters in the Parameters tab

Another way is to list each key and value in the Parameters tab as shown below.
Parameters Tab
​

4. Authorization

Acho supports four types of authorization to validate API access.
  • None (default): If your API doesn't require authorization, you can select None.
  • Basic Auth: It requires a username and a password.
  • Bearer Token: It requires a Bearer Token.
  • OAuth Client: You will need to set up an OAuth Client and use it.
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.

4.1 OAuth Client

  1. 1.
    When creating an API Resource, you can select OAuth Client for the Authorization Type.
  2. 2.
    Click + if you don't have one.
  3. 3.
    Enter your info, please name it well, then click Add.
    ​
  4. 4.
    A new tab will be opened, if it's a login page, you can log in, and after you see an object (including an access token), you can close that tab. You may see the object immediately, which means you are logged in already, you can just close the tab.
  5. 5.
    Click Next.
  6. 6.
    Select the client you just created.
    ​
  7. 7.
    You are all set, you can test your API now.

5. Headers (Optional)

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.

6. Data Format

Data format is the output scheme of the data from your API.

JSON (default)

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

JSON - JSON Path (optional)

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

CSV

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

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
​

7. Multiple Requests

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 to a specific customer_id at a time.

Method 1: Iteration Requests (Pagination):

It's to retrieve data depending on the row number. This method splits data into several batches based on the row number and only retrieves 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 limit or page_size.
  • Start Parameter Key: A parameter to decide where to start to retrieve data. Most of the APIs call this parameter start or page. The Start for most APIs is either 0 or 1. If the pagination is by page, the Step is usually 1 (just like flipping pages). If the pagination is by number, the Step is usually the same as the Request Limit number.
Two most common examples:
Pagination by number
Pagination by page

Method 2: Recursive Requests (by field):

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 Key is dependent on Field 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.
​

Method 3: Loop

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

8. API Update

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

Set up dynamic date ranges

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.

URLs

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

​

Parameters

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

​

​
Previous
Asana
Next
AWS CloudTrail
Last modified 14h ago