API integration is the final step for you to transfer data to Alipay+ server which is deployed in local IDC. Next, this document will provide a detailed introduction of the API details, which will be useful for your technical developers.

Before you start

1. Make sure you have completed the configuration work and obtained the SDK installation package as guided in preparation documentation.
2. Make sure data schema have been aligned with Alipay+.
3. The SDK only supports Java language. Please make sure you have prepared the Java environment.

You only need to integrate one API to transfer data, which supports highly secure data encryption and transmission. Then, Please continue reading the documentation as it provides a detailed explanation of the API's workings and fields.

How it works

Interaction flows

The following figure shows the interaction flows among wallet server and Alipay+ server:

1. Data developers generates raw data according to the aligned data schema.
2. Raw data can be stored in many storage formats, such as relational databases, sftp files, etc., as long as it can be consumed by Server Biz in your application.
3. Similarly, there are many ways to consume data, such as pushing data to the application or pulling data from the source storage at regular intervals, which depends on the wallet's application architecture.
4. The wallet application can upload data by batch. The Alipay+ side can accept up to 20 batches per second, with each batch containing 100 rows of data for transmission during the integration phase. Assuming that 25 million lines of data need to be uploaded daily, and the number of machines used for transmission is N, with M batches per second per machine, it is necessary to ensure that NM<=20 first. The time required to complete the data transmission is 70/(N*M) hours.

1. Such as you use 10 machines to transmit data at the same time, with each machine sending 1 batch of data per second (N=10, M=1), it will take 7 hours to complete the data transmission.
2. According to the data schema, the daily update needs to be completed before 10:00 a.m. in the GMT+8 time zone. Please select an appropriate transmission rate.

5. DataHub SDK will encrypt each field in each line of uploaded data one by one, and then transmit the entire batch of data uniformly.

Sequence diagram

The following figure illustrates the message communication workflow between wallet server and Alipay+ server:

1. Wallet application construct a request message in a proper format and upload raw data to DataHub SDK, which is deployed in wallet server. Raw data will never be transmitted outside of the wallet server to ensure data security.
2. DataHub SDK will read the configuration information from keys.properties (as guided in Initialize SDK documentation Chapter 2-step 6) and encrypts the raw data. Then transfer encrypted data to Alipay+ server.
3. After receiving the data, the A+ server will verify the data, including the identity of the data uploader, data permissions. If the verification is successful, the encrypted data will be stored in a secure data source. All data operations are executed in a Trusted Execution Environment, there will be no leakage of the raw data.
4. Data upload result will be returned to wallet application. Referring to the result code provided in the appendix below, you can differentiate whether the current request was successful, the corresponding error reason, and how to handle it.

API design

Method

com.alipay.idatahub.client.DataUploadClient.uploadData

Sample request

{
  "dataUuid": "6b42f8c92190425fa2d8d92ff723a11a",
  "data": [
    "{
      "id": "218826****",
      "userName": "alice",
      "userAge": "24",
      "screenWidth": "6.1"
    }"
  ]
}

• dataUuid means the unique ID to identify data asset, you can get the information as guided in Preparation documentation step 1.
• data refers to the raw data in each batch, containing 100 rows. Each element in the data list represents a row of data, and data value must follow the actual schema definition. each row of data follows the K-V format, where "K" is the field name and "V" is the field value. Here's a detailed example:

data schema

data

It should be noted that even if the data type is Bigint or Double, you need to ensure that all field values are converted to String format to avoid encoding issues during data consumption in JSON format.

[
  {
    "id": "218826****",
    "userName": "alice",
    "userAge": "24",
    "screenWidth": "6.1"
  }
]

Sample response

{
  "resultStatus": "S",
  "resultCode":"SUCCESS",
  "resultMsg": "the request is successful",
  "traceId": "2911524530937576035"
}

• resultStatus indicates the result of processing a request. Following appendix describes each result status.
• resultCode indicates the detailed scenarios of result. Wallet Application can perform corresponding actions based on the resultCode. You can see appendix below for more details.
• resultMsg refers to the description of resultCode.
• traceId refers to the unique identifier of the current request, used for fast trouble-shooting.

Appendix

ResultStatus Enum

ResultCode Enum