Headers

Parameters

Parameter Name	Type	Required	Description
X-Fresns-App-Id	String	required	Key App ID Path: Panel->AppCenter->Keys
X-Fresns-Client-Platform-Id	Number	required	Platform ID, matching the "platform" of the key Path: Panel->AppCenter->Keys Check the ID number corresponding to the platform
X-Fresns-Client-Version	String	required	Your client version, semantic version is recommended
X-Fresns-Client-Device-Info	String	required	Interaction Device Information session_logs->device_info The object information is first compressed and converted to a string, which is then Base64 encoded.
X-Fresns-Client-Timezone	String	optional	UTC time zone (for processing content time values) Leave blank to use database time zone
X-Fresns-Client-Lang-Tag	String	optional	Language Tag (output default language if left empty) Path: Panel->Systems->Languages
X-Fresns-Client-Content-Format	String	optional	Content format (list and detail of posts and comments), leave blank then output as is. Pass the html reference to convert content to html format (\n for text content to <br>, Markdown content to HTML)
X-Fresns-Aid	String		Account parameter (regarded as unlogged in account if left empty)
X-Fresns-Aid-Token	String		Account identity credential (If aid exists, it cannot be empty)
X-Fresns-Uid	Number		User parameter (regarded as unlogged in user if left empty)
X-Fresns-Uid-Token	String		User identity credential (If uid exists, it cannot be empty)
X-Fresns-Signature	String	required	Signature generation rules
X-Fresns-Signature-Timestamp	String	required	Signature generation time (Current UTC+0 Unix timestamp, in seconds or milliseconds)

Register and Login Process

1. Start
   • Register /api/v2/account/register
   • Login /api/v2/account/login
   • After successful registration or login, obtain the account voucher.
     • aid: data.sessionToken.aid
     • aidToken: data.sessionToken.token
2. Judge the number of users of the account data.detail.users
   • 1
   • 2 or more Presenting the "Select User" view
3. Determine if there is a password data.detail.users[x].hasPassword
   • No password
   • With password Presenting the "Password Entry Box" view
4. Login User
   • /api/v2/user/auth
   • After the user login successfully, obtain the user credential.
     • uid: data.sessionToken.uid
     • uidToken: data.sessionToken.token
5. End

   • When the account has only 1 user and no password, it is recommended to let the user login directly without perception.

Introduction of operation mode

• Configuration Table key name site_mode
  • Public mode, with the key value public
  • Private mode, with the key value private
• Get Method: /api/v2/global/configs?keys=site_mode
• The introduction page of each interface has two modes of account and user parameters that must be transferred.
  • aid must be passed, which means that you must login to the account to request the interface. At this time, the token parameter is the token of the account
  • When uid must be passed, aid must also be passed.which means that the user must log in to the "account user" to request the interface. At this time, token parameter is the user's token

Signature generation rules

// Parameters participating in the singing process in headers
const SIGN_PARAM_ARR = [
    'X-Fresns-App-Id',
    'X-Fresns-Client-Platform-Id',
    'X-Fresns-Client-Version',
    'X-Fresns-Aid',
    'X-Fresns-Aid-Token',
    'X-Fresns-Uid',
    'X-Fresns-Uid-Token',
    'X-Fresns-Signature-Timestamp',
];

• Encapsulation method can be referred to in PHP App\Helpers\SignHelper::makeSign($signMap, $appSecret)
• As for other client ends, please refer to the following procedures:

1. Extract the headers parameters participating in the signing process.

// No login
{
    "X-Fresns-App-Id": "yh1OJ7WL",
    "X-Fresns-Client-Platform-Id": 2,
    "X-Fresns-Client-Version": "2.0.0",
    "X-Fresns-Signature-Timestamp": 1674161913192
}

// Logged in account
{
    "X-Fresns-App-Id": "yh1OJ7WL",
    "X-Fresns-Client-Platform-Id": 2,
    "X-Fresns-Client-Version": "2.0.0",
    "X-Fresns-Aid": "wIfu6jaF",
    "X-Fresns-Aid-Token": "uoX1hk6SHUgB2MFGJwNx38dem9DA7Vsz",
    "X-Fresns-Signature-Timestamp": 1674161913192
}

// Logged in user
{
    "X-Fresns-App-Id": "yh1OJ7WL",
    "X-Fresns-Client-Platform-Id": 2,
    "X-Fresns-Client-Version": "2.0.0",
    "X-Fresns-Aid": "wIfu6jaF",
    "X-Fresns-Aid-Token": "uoX1hk6SHUgB2MFGJwNx38dem9DA7Vsz",
    "X-Fresns-Uid": 782622,
    "X-Fresns-Uid-Token": "PqBpwPLJgfd1sH0X5JffYFGxTSc8RW7c",
    "X-Fresns-Signature-Timestamp": 1674161913192
}

2. Sort the parameter names from the smallest to the biggest according to the ASCII character (lexicographical order).

{
    "X-Fresns-App-Id": "yh1OJ7WL",
    "X-Fresns-Client-Platform-Id": 2,
    "X-Fresns-Client-Version": "2.0.0",
    "X-Fresns-Aid": "wIfu6jaF",
    "X-Fresns-Aid-Token": "uoX1hk6SHUgB2MFGJwNx38dem9DA7Vsz",
    "X-Fresns-Uid": 782622,
    "X-Fresns-Uid-Token": "PqBpwPLJgfd1sH0X5JffYFGxTSc8RW7c",
    "X-Fresns-Signature-Timestamp": 1674161913192
}

3. Splice new parameters sorted into character strings with the right format of URL key value.

X-Fresns-Aid=wIfu6jaF&X-Fresns-Aid-Token=uoX1hk6SHUgB2MFGJwNx38dem9DA7Vsz&X-Fresns-App-Id=yh1OJ7WL&X-Fresns-Client-Platform-Id=2&X-Fresns-Client-Version=2.0.0&X-Fresns-Signature-Timestamp=1674161913192&X-Fresns-Uid=782622&X-Fresns-Uid-Token=PqBpwPLJgfd1sH0X5JffYFGxTSc8RW7c

4. Splice &AppSecret={app_secret} to obtain the character string to be signed.

X-Fresns-Aid=wIfu6jaF&X-Fresns-Aid-Token=uoX1hk6SHUgB2MFGJwNx38dem9DA7Vsz&X-Fresns-App-Id=yh1OJ7WL&X-Fresns-Client-Platform-Id=2&X-Fresns-Client-Version=2.0.0&X-Fresns-Signature-Timestamp=1674161913192&X-Fresns-Uid=782622&X-Fresns-Uid-Token=PqBpwPLJgfd1sH0X5JffYFGxTSc8RW7c&AppSecret=qUiEaDNQh2IpvGHOKlTMx7ujn8t1CZWX

5. Perform MD5 operation (32-digit lowercase) against the signed character signature to obtain the signature value.

2174eaeab76fb6a3790ed4f7ebb2edfb

Cache Introduction

• To facilitate global calls to various configuration data, we have developed clients that use global function wrappers. See the web-engine composer package.
  • fs_api_config('item_key') Call the parameters of the /api/v2/global/configs interface
  • fs_lang('KeyName') Call the fs_api_config('language_pack_contents') parameter
  • fs_code_message('code') Call the parameters of the /api/v2/global/code-messages interface
  • fs_account('key') Call the data parameter of the /api/v2/account/detail interface
  • fs_user('key') Call the data parameter of the /api/v2/user/{uidOrUsername}/detail interface
  • fs_user_panel('key') Call the data parameter of the /api/v2/user/panel interface
  • Other...
• Since global data may be used on every page, we use caching on the client side in order to avoid frequent requests to the interface affecting the loading speed.
• Configuration Items: We use /api/v2/global/configs?keys=cache_datetime,cache_minutes to detect cache expiration, so that cache expiration will be automatically re-cached.
  • cache_datetime Datetime of last server-side configuration.
  • cache_minutes Recommend that the client caches be saved for a maximum number of minutes, with a value of null indicating no limit. If there is no limit, it is suggested to periodically request the interface and only obtain the cache_datetime,cache_minutes configuration, compare the validity period with that of the local one. If they are inconsistent, it means that the server has updated the configuration, so please re-cache it.
• User Profile: We recommend caching user data after login. When the user interacts with features such as like, publish, or modifying their profile, we suggest retrieving the user data again and recaching it.