Open Platform Plugin

Version

Note:

For the project where the plugin of V3.0.8 or earlier versions is installed, the length of the secret filed in the fr_open_app table of the FineDB configuration database is varchar 256 by default. In the plugin of the V3.0.8 version, the key encryption storage is added. After you upgrade the plugin from an earlier version to V3.0.8 or later versions, you need to manually change the field length of the database to 1000.

Application Scenario

You can integrate FanRuan‘s product capabilities and custom data services into your own service systems through the open platform by accessing applications and invoking APIs.

Multiple function APIs are open for you to conveniently and quickly apply FanRuan‘s product capabilities.

Function Description

Fanruan offers the Open Platform plugin to:

1. Provide secure, flexible, standardized, and effective web services for developers to quickly build applications, manage FanRuan systems and reports, and conduct data services within your own service systems.

2. Provide a unified platform configuration to manage client API permissions and security authentication.

3. Provide log management functions to view the requests to and access status of APIs and applications.

Service Process

Public API

FanRuan provides related API documents to help you understand and use the built-in APIs of the open platform.

The following API documents are provided as official examples for users who have the ability to integrate products independently. Our technical support is not responsible for maintaining API examples or answering the usage questions.

Note:

The APIs need to work with the Open Platform plugin.

The API documents have no English version at the moment. You can use the browser's built-in translator to translate the web page to view the documents.

Plugin Installation

You can download the Open Platform plugin.

For details about how to install the plugin in the designer, see Designer Plugin Management.

For details about how to install the plugin on the server, see Server Plugin Management.

Note:

Disable the same-series plugins (if any) before upgrading the Open Platform plugin, or restart the server after upgrading the plugin.

The same-series plugins include Open Platform - FineBI API, Open Platform - FineReport API, Open Platform-Platform Login Authentication API.

Page Overview

After this plugin is successfully installed, log in to the decision-making platform as the admin and choose System Management > Open Platform to enter the function page, as shown in the following figure.

Note:

APIs are updated in the plugin of the new version V3.0.0. You can click Show Earlier-Version API or Hide Earlier-Version API in the top right corner.

The following table lists functions of each module.

API Management

All configurations for data interaction services betweeen third-party systems and FineReport are included in API Management.

(1) Group Management

The left part of the API Management page is the group area. Built-in multiple groups are available on the platform. You can add or delete groups according to your needs.

You cannot delete or edit built-in groups.

You can delete and edit non-built-in groups. APIs in the deleted groups will be automatically moved to the default group.

(2) API Management

Multiple APIs can be saved in each group. Some common built-in APIs are available on the platform. You can also customize APIs yourselves.

You can edit, copy, and regroup built-in APIs, but cannot delete or disable them.

You can edit, copy, regroup, delete, and disable non-built-in APIs.

Note:

In the plugin of the V3.0.0 version, the Whitelist attribute has been added for you to set an IP address whitelist for a single API so that API access can be controlled.

Application Management

(1) New Application

In Application Management, you can create applications by adding events.

You can click Application Management, click Add, set the relevant content, and click OK to add an application.

The automatically generated application ID and key can be used as access credentials of third-party systems for API authentication.

(2) Application Management

You can add applications, edit/copy/disable added applications, and delete added applications one by one or in batches. You can reset keys during editing.

Authentication Method

The authentication method is used to secure external services. All application APIs support the self-signed token authentication method.

In addition, the platform has three bulti-in alternative authentication methods. You can also add authentication methods according to your needs.

Universal Authentication Method

The self-signed token authentication is one authentication method naturally supported by all application APIs. Whether or not an alternative authentication method is selected, this authentication method is still available.

This authentication method is used to authenticate login information through access_token which needs to be obtained first through the application ID and key. The following figure shows how to obtain access_token.

The request URL to obtain the token is $HOST/sp/client/api/token.

The API method is POST.

Write the application ID and key into Query or Headers. For details abut the application ID and key, see section "Application Management." The following figure shows the overall effect.

Write the obtained access_token into VALUE of Headers, and set KEY to clientToken in this case. According to the configuration of the corresponding API, modify the API method and URL to invoke the corresponding API.

The following figure shows the overall effect.

Built-in Alternative Authentication Method

The open platform has three built-in alternative authentication methods, which can only be edited and copied but cannot be deleted or disabled, as shown in the following figure.

Authentication   Method	Description
SM2 Signature Authentication	The SM2 elliptical curve algorithm is used for encryption and decryption. You can perform authentication by the application ID and the signature generated using the application ID, key, and timestamp. Set priKey to the actual key and timeout to the timeout threshold (seconds). Set _sign_ to SM2(Application ID+Key+Timestamp)+Timestamp. Add _sign_={Calculated value} and client_id={Application ID} into Headers to access the application directly.
Digest Signature Authentication	If token authentication cannot be used, digest algorithms (such as SM3, MD5, and SHA-256) can be used for authentication through the application ID and the signature generated using the application ID, key, and timestamp. Set method to the actual digest algorithm and timeout to the timeout threshold (seconds). Set _sign_ to Digest algorithm(Application ID+Key+Timestamp)+Timestamp. Add _sign_={Calculated value} and client_id={Application ID} into Headers to access the application directly. Note: You are advised to use this authentication method for higher security. Example: client_id=203bc7b8db1d423fb55824150327ef98 secret=98ffd41b86db4868a6875f57e6974bbc timestamp=1600166180321 Digest algorithm=MD5 timeout=300s _sign_=MD5(client_id+secret+timestamp)+timestamp= EE6E14BCEC5724C3BC6FC08AFC5C2B111600166180321 (in this case)
Direct AK/SK Authentication	You can use the application ID and key directly as authentication credentials to directly invoke the service. No configuration item is available. The configuration information on the authentication method editing page cannot be edited. Add client_id={Application ID} and secret={Key} into Headers to directly access the application. Note: For security reasons, this authentication method is not recommended.

Custom Alternative Authentication Method

You can add authentication methods. You can edit/disable non-built-in authentication methods, and delete these methods one by one or in batches.

On the Authentication Method page, you can click Add, set the relevant configuration items, and click OK to add an authentication method.

Note:

In some environments using NGINX, the underscore in client_id will be recognized as invalid.

The current solution is to allow both client_id and clientId to be recognized, which has been realized in the iteration for compatibility.

Permission Management

For non-public APIs, permission authentication is required for all invokings. The range of invokable APIs varies according to different scenarios and applications. The administrator can configure permissions in Permission Management.

Public APIs can be invoked freely without permission authentication constraints.

Note:

Currently, there is no group permission. That is to say, even if the permission is enabled for a certain group, it is actually the permission of the API in the current group that is assigned to a certain application.

If the API is re-grouped later, or new APIs are added to that group, the previously-set API permissions will remain unchanged.

For example, if you enable the group permission for Directory Tree Management of an application, the permission on all subordinate APIs is enabled. If an API in this group is re-grouped, the permission is still enabled for this API. If new APIs are added to this group in Directory Tree Management, the permission is disabled for this API.

Log Management

The administrator can view the API request frequency and details on the Log Management page.

Global Setting

On the Global Setting page, the administrator can set Max Request Rate Per Second and Max Flow, and click Save for the settings to take effect.