Overview
Version
| FineBI Version | Functional Change |
|---|---|
6.0 | / |
Function Description
FineBI allows you to call API data through GET and POST for Web integrations.
This document introduces the basic knowledge of API for you to perform Web integrations through FineBI.
Viewing Method of the API Documentation
The API documentation generally includes the API introduction, API address, request method, request parameter, response content, error code, and instance.
| Content | Description |
|---|---|
API introduction | Briefly describes the logic and purpose of the API. For example, an API used for sending messages/querying weather is described in this part. |
API address | Represents a network address, which needs to be called to retrieve the response content. |
Request method | Usually includes GET and POST. For other methods, you can refer to the following figure.  Note:
|
Request parameter | Carries variables used to pass information. That is, this part specifies the name, type, and rule (optional/mandatory) of the field that needs to be requested.
|
Response content | Includes field names and rules returned by the API. |
Error code | Includes the API errors classified by codes to help you quickly figure out causes and solve errors. |
Instance | Includes the response content during the actual calling. |
Request Parameter
GET Request
The GET method is commonly used to retrieve data on the server.
The GET method allows you to concatenate parameters at the end of the URL and transfer parameters only in the text format.
The GET request can transfer a small volume of data (about 4 KB, which varies in different browsers).
Since information is displayed on the address bar, the GET request has low security.
The GET request boasts fast speed, and it is usually used in scenarios with low security requirements.
The GET request can contain Headers parameters.
The GET request can transfer parameters through the URL (the general way).
In the GET request, parameters such as Parameters and Queries are all transferred through the URL.
In Postman, you can directly transfer parameters through the URL. You can also set KEY and VALUE in Params to allow parameters to be concatenated automatically.
POST Request
The POST request has higher security than the GET request in terms of data submissions.
The POST request can transfer a large volume of data, with no requirements on data length.
The POST request can be used in scenarios with high security requirements (such as password-based verification) or large amounts of data to be submitted (such as file uploading or document publishing).
The POST request generally consists of URL, Headers, and Body. If Parameters/Queries exists in the API documentation of the POST request, parameters should be transferred through the URL like the GET request. Parameters in the API documentation of the POST request generally refer to those in the Body part.
The following table describes some content types.
| Type | Description |
|---|---|
application/json (data in JSON format and generally in raw-JSON format) | This format (such as {"name":"Roxy","password":"123"}) is the most common one. The following figure shows Headers in this case. |
text/plain (data in plain text format and generally in raw-Text format) | Example: name:ziv, password:123 |
text/xml (data in XML format and generally in raw-XML format) | Example: <?xml version="1.0" encoding="UTF-8" ?> <name>ziv</name> <password>123</password> |
multipart/form-data | In this format, table data is processed as messages (unit: tag) separated by separators. Since each part in the multipart/form-data request is separated by boundary, you can upload data through key-value pairs (for uploading multiple files or values). |
application/x-www-form-urlencoded | Through this content type, data in the table can be converted into key-value pairs separated by ampersands (&). |
Authentication Method
You need to log in to all WEB APIs in FineBI for use, except for the login API.
1. If you want to officially use APIs, you are advised to configure the single sign-on function. Otherwise, you need to perform login repeatedly after embedded integration.
2. If you are in a testing stage, you can log in to FineBI, obtain the token parameter, and include the parameter when debugging other APIs.
This section introduces two methods for obtaining and using the token parameter. You can choose either one.
fine_auth_token
1. Log in to the FineBI system as a user.
2. Press the F12 key to open the developer tools, choose Network > Headers, and obtain the value of fine_auth_token, as shown in the following figure.
3. Add the parameter and its value into Params and concatenate ?fine_auth_token=token to the end of the URL.
Authorization
1. Log in to the FineBI system as a user.
2. Press the F12 key to open the developer tools, choose Network > Headers, and obtain the value of token in authorization, as shown in the following figure.
3. Go to Headers and set KEY to Authorization and VALUE to a combination of Bearer and the obtained token value.
Note the space after Bearer. You are advised to directly copy and paste the content in the highlighted yellow area of the above figure.
Obtaining Various IDs
You can obtain the parameter values of some APIs through other APIs. But sometimes you need to obtain ID values for testing a single API during debugging. This section introduces how to obtain these ID values.
| ID | Obtaining Example |
|---|---|
User ID | Choose My Analysis. The current user's ID is behind __my_analysis__ of the URL. |
Folder ID in My Analysis
| Select a folder. The current user's ID is behind folder/ of the URL. |
Analysis Subject ID in My Analysis
| Select an analysis subject. The subject ID is behind subject/ of the URL. |
Data Table ID in My Analysis
| Select a data table. The data table ID is behind table/ of the URL. |
Component ID in My Analysis
| Select a component. The component ID is behind widget/ of the URL. |
Dashboard ID in My Analysis
| Select a dashboard. The dashboard ID is behind report/ of the URL. |
Folder ID in Public Data
| Select a folder. The current user's ID is behind folder/ of the URL. |
Original Name of the Table in Public Data
| Select a dataset. The original name of the table is behind table/ of the URL. |
Other Interfaces
Cross-domain Login Interface
You can log in to the FineBI system through this API.
URL: /login/cross/domain?fine_username=name&fine_password=password&validity=-1&callback=myfunction
Request Method: GET
Customization Before Export
You can add some custom operations (such as encryption customization for to-be-exported files) through this API before exporting components or globally exporting templates as Excel files.
API: ExportHandleProvider
package com.finebi.stable.fun;
import com.fr.stable.fun.mark.Mutable;
import java.io.OutputStream;
/**
* Created by Hiram on 2018/11/14.
*/
public interface ExportHandleProvider extends Mutable {
String XML_TAG = "ExportHandleProvider";
int CURRENT_LEVEL = 1;
/**
*
* @param originalOutputStream original export stream
* @param type export type
* @return stream after processing
*/
OutputStream handleStream(OutputStream originalOutputStream, ExportType type);
}The following example source code shows how to calculate the size of the exported file and output the result in the log. Write in a CountExportHandle class for interception and processing to return a CountOutputStream class. The number is counted when you write in CountExportHandle and the size is output when you close the stream.
CountExportHandle:
import com.finebi.stable.fun.ExportType;
import com.finebi.stable.fun.impl.AbstractExportHandleProvider;
import java.io.OutputStream;
public class CountExportHandle extends AbstractExportHandleProvider {
@Override
public OutputStream handleStream(OutputStream originalOutputStream, ExportType type) {
return new CountOutputStream(originalOutputStream);
}
}CountOutputStream:
import com.fr.log.FineLoggerFactory;
import java.io.IOException;
import java.io.OutputStream;
public class CountOutputStream extends OutputStream {
private OutputStream out;
private int count;
public CountOutputStream(OutputStream out) {
this.out = out;
}
@Override
public void write(int b) throws IOException {
count++;
out.write(b);
}
@Override
public void write(byte[] b) throws IOException {
count += b.length;
out.write(b);
}
@Override
public void write(byte[] b, int off, int len) throws IOException {
count += len;
out.write(b, off, len);
}
@Override
public void flush() throws IOException {
out.flush();
}
@Override
public void close() throws IOException {
FineLoggerFactory.getLogger().info("===== export length: {} ======", count);
out.close();
}
}
Obtaining the Complete Directory Tree
You can obtain the directory panel on the homepage of FineBI through this API.
URL: /v10/view/entry/tree
Request Method: GET
Note:To use this API, fine_auth_token needs to be carried for authentication.
Page Integration Interface
You may want to integrate the backend management page of FineBI into your own system to unify the portal. This section introduces the page integration APIs supported by FineBI.
1. API
The following table describes the scope of management menus that support individual page integration.
The URL for calling each API is http://IP address:Port number/projectName/decision/CalledAPI.
| Management Menu | Called Interface | Note |
|---|---|---|
Directory Management | /directory | / |
User Management | /user | / |
Permission Management | /privilege | / |
Task Schedule | /timer | Global setting is not supported. |
2. Example
Log in to the FineBI system as the admin and and access Directory Management through http://localhost:37799/webroot/decision/directory, as shown in the following figure.
Note
No Permission on Page Access
Problem
After you (non-administrator) log in to the FineBI system, the following error message is displayed when you access http://IP address:Port number/webroot/decision/Called API.
Solution
You can obtain the permission of this page by referring to the document Permission.
Rejected Connection Request
Problem
An error occurs when you embed FineBI into other pages through the iframe page, as shown in the following figure.
Solution
Log in to the FineBI system as the admin, choose System Management > Security Management > Security, and disable Prevent Clickjacking, as shown in the following figure.
Unsupported URL in JSON Format on the Server
If some servers do not support the JSON object transferred through the URL in FineBI, you need to encode the JSON parameter values in the URL through encodeURIComponent().
For example, you need to change dir={"name":"New Dashboard 12","catalog":[]} into encodeURIComponent(JSON.stringify({"name":"New Dashboard 12","catalog":[]})).
The result after encoding is
dir=%7B%22name%22%3A%22%E6%96%B0%E5%BB%BA%E4%BB%AA%E8%A1%A8%E6%9D%BF12%22%2C%22catalog%22%3A%5B%5D%7DReturned Error Code
errorCode will be returned if an error exists on the backend when you perform system integration.
