REST API

Connect an HTTPS JSON API to Fresco BI. Each endpoint you declare becomes one table: Fresco BI calls it, follows the pagination, takes the array of records at the records path and imports it into a Data Table. Fresco BI only sends GET requests, or POST requests with the JSON body you give.

Feature	Supported
Import	Yes
DirectQuery	No
SSL/TLS	HTTPS only, always verified
SSH tunnel	No
Cloud	Yes
On-premises (via Gateway)	No

Prerequisites

• An API reachable from the internet over HTTPS, by a DNS host name (an IP address in the URL is refused).
• Endpoints that answer with JSON (application/json or a +json type) holding an array of records.
• A credential for the API, if it needs one.

Step 1: Create a read-only credential

Create a credential that can only read the endpoints you need, for example:

• an API key or token with a read-only scope;
• a service user with a read-only role (for basic authentication);
• an OAuth2 client allowed the client credentials grant, with read-only scopes only.

The credential is stored encrypted and sent only in request headers (or in the token request for OAuth2). It never appears in errors or logs.

Step 2: Allow network access

Cloud. If the API has an IP allow-list, allow Fresco BI’s outbound IP addresses (the setup guide beside the data source form lists them) on port 443 (or the port in your base URL).

Fresco BI refuses private, loopback and metadata addresses, follows redirects only to the same host and port (at most 3), and the Link header pagination must stay on the base URL’s host. There is no SSH tunnel and no On-premises (Gateway) option for this connector.

Step 3: Fill in the form

The web form for the REST API is not available yet. The source takes these settings:

1. Base URL: https:// only, for example https://api.example.com.
2. Endpoints: 1 to 50, one table each. Every endpoint has the fields below.
3. Table name: unique per source.
4. Endpoint path and query: starts with /, for example /v1/customers?page={page}&per_page={limit}. Only {page}, {offset}, {cursor} and {limit} may be used.
5. Records path: where the array of records is: $ (default, the whole answer) or a path like $.data.items, up to 10 levels.
6. Method: GET (default) or POST. JSON body (POST): a JSON object or array, at most 10 KB, sent with POST only.
7. Headers: up to 20 extra headers. Authorization, Proxy-Authorization, Host, Cookie, Content-Length, Transfer-Encoding, Connection, Upgrade and TE cannot be set here.
8. Authentication (default none), see the table below.
9. Pagination (default none), see below.
10. Page size ({limit}): 1 to 1,000 (default 100). First page number: 0 or 1 (default 1). Maximum pages: 1 to 100 (default 100).
11. Requests per second: 1 to 10 (default 2).
12. CA certificate (PEM): optional, for an API whose certificate is signed by a private CA.

Authentication	You enter
none	nothing
api_key	API key; sent in API key header (default X-API-Key)
bearer	Bearer token; sent as Authorization: Bearer
basic	User name and Password
oauth2_client_credentials	Token URL (https), Client ID, Client secret, optional Scope

For OAuth2, Fresco BI posts grant_type=client_credentials to the token URL with the client ID and secret as HTTP Basic, then sends the access token as a bearer token and renews it before it expires.

Pagination

Pagination	How the next page is found
none	One request per endpoint
page	{page} goes up by 1; stops on a page shorter than the page size
offset	{offset} goes up by the records read; stops on a short page
cursor	The value at Next cursor path goes into {cursor}; stops when it is empty or repeats
link	Follows the Link: <...>; rel="next" header

For page, offset and cursor, every endpoint path must contain that variable. Every style stops on an empty page.

Limits

• At most 100 pages per endpoint. If more data is left after Maximum pages, the load fails rather than import part of the data.
• At most 100,000 records per table, 50 MB per answer and 500 MB per load.
• Columns are inferred from the first 1,000 records; at most 500 columns. Nested objects are flattened one level (customer_name); deeper objects and arrays are kept as JSON text.
• An answer of 429 is retried up to 3 times, honouring Retry-After up to 60 seconds.

Troubleshooting

• The server rejected the user name or password. The API answered 401 or 403, or the token request failed. Check the authentication type, the credential and the API key header name.
• The database or object was not found on the server. The endpoint answered 404. Check the base URL and the endpoint path.
• The connection settings are not valid: check the marked fields. The API answered another 4xx status (often a bad query parameter), or the URL is not https:// with a DNS host name.
• The source returned a data type this connector does not support. The answer is not JSON, or the records path does not point to an array. Check the records path.
• A size or concurrent-connection limit was exceeded. Too many pages, records or columns, an answer over 50 MB, or still 429 after the retries. Narrow the endpoint, raise the page size, or lower requests per second.
• The host is in a blocked range (private, loopback or metadata). A database inside a private network needs an On-premises connection through a Gateway. The host resolves to a private address, the URL uses an IP address, or a redirect or Link page points to another host.
• The host name could not be resolved (DNS). Check the Host field. Check the host in the base URL.
• No connection could be opened to this host and port. Check the host, the port, and that the firewall allows Fresco BI’s IP. The API is down, answered with a 5xx error, or blocks Fresco BI’s outbound IP addresses (the setup guide beside the data source form lists them).
• The SSL connection could not be set up with the chosen mode. Check the SSL mode and the CA certificate. The API certificate is not trusted; paste its CA into the CA certificate field.