Web Page Integration FAQs

Version

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.

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: GET and POST are supported in FineBI.
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. URL to transfer parameters Headers (request header) Body (request content)
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.

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.

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.

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.

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();
    }
}

Note:

This API requires secondary development.

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.

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.

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%7D

Returned Error Code

errorCode will be returned if an error exists on the backend when you perform system integration.