This document describes the specifications for RESTful APIs provided by Business View.
Overview
The Ant Blockchain Business View service is a deployable component which is independent from the blockchain. It provides developers with the following capabilities:
Provides the ability to read and write data on the blockchain through RESTful API. Even if you are not proficient in working with Java SDK, Business View can help you use with Blockchain efficiently.
Allows you to use MySQL as an off-chain database and automatically synchronizes on-chain data in near real-time with a maximum delay of 10 seconds. This makes data statistics and analytics easier.
Automatically de-serializes on-chain data based on the Data Classification Configuration. This process helps you perform queries on specified keywords of your business, and reduces the pressure of read operations on the blockchain. This can be combined with data analytics tools and solutions including Alibaba Cloud MySQL and BI, to further explore the value of on-chain data.
APIs of Business View can be broadly classified into the following two categories:
Sending notary (API 1), Querying notary (API 2), Sending big file notary (API 3), and Querying big file Notary (API 4). These four APIs are closely related to your Data Classification configuration on the blockchain. You can add multiple categories, and Business View provides a specific sending notary API and a querying notary API for each category. We highly recommended this approach.
Except for the APIs mentioned above, Ant Blockchain supports other notary models, including EncryptNotary, HashOnlyNotary, and various others. Usages of these notary models are provided in API 5, API 6, and API 7. For more information regarding notary models, please see Notary Transaction Model of Ant Blockchain.
1. Send Notary to Blockchain
This API is automatically generated based on Data Classifications, one API for each category.
RESTful URL: api/{categoryName}
HTTP Method: POST
Request parameters
Based on the definition of the category, submit a complete category.
Returns json text.
RESPONSE
Parameter | Datatype | Is mandatory | Specification |
---|---|---|---|
responseData | string | no | Transaction hash |
success | bool | yes | Request is successful or not |
errMessage | string | no | Error message |
The following is a sample. Assume that we have Data Classification Configuration in our schema.txt as below.
GuestInfo {
// name, cannot be null
String userName;
// email address, cannot be null
String email;
// birthday, cannot be null
String birthday;
}
The generated API would be: http://{your_server_ip}:8080/api/guestInfo. Note that the URL path begins with a lowercase letter, therefore the category name GuestInfo becomes guestInfo in the API.
Add HTTP Request Headers: Content-Type:application/json, HTTP Request Body is defined based on the definition of GuestInfo, as shown below.
{
"userName":"Kate",
"email":"kate@163.com",
"birthday":"20180101"
}
Test the API with curl.
curl -X POST \
http://{your_server_ip}:8080/api/certFile \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F 'userName=Kate' \
-F 'email=kate@163.com' \
-F 'birthday=20180101'
A successful HTTP response is as follows:
{
"errMessage" : "",
"responseData": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c",
"success" : true,
}
2. Query Notary Data
This API is automatically generated based on Data Classifications, one API for each category. The fields of the category and the transaction hash can be used as the key to query transactions that meet the criteria.
RESTful URL: api/{categoryName}Get
HTTP Method: POST
Request parameters
Parameter | Datatype | Is mandatory | Specification |
---|---|---|---|
key | string | no | Key of the query criteria |
value | string | no | Value of the query criteria |
pageSize | int | no | Page size of the return data, less than 100 |
pageNumber | int | no | Page Number of the return data, starts with 1 |
Data structure of return value
RESPONSE
Parameter | Datatype | Is mandatory | Specification |
---|---|---|---|
responseData | list | no | Data of transactions, returns null when no transactions meets the criteria |
success | bool | yes | Request is successful or not |
errMessage | string | no | Error message |
totalCount | int | no | The length of responseData |
The following is a sample. We use the category GuestInfo described in API 1 , the URL path would be http://{your_server_ip}:8080/api/guestInfoGet .
Add HTTP Request Headers: Content-Type:application/json. Assume that we are querying notary data and userName is Bob with a page size of 5 and page number of 1, the HTTP Request Body is shown below.
{
"key":"userName",
"value":"Bob",
"pageSize":5,
"pageNumber":1
}
Test the API with curl.
curl -X POST \
http://{your_server_ip}:8080/api/guestInfoGet \
-H 'Content-Type: application/json' \
-d '{"key":"userName","value":"Bob","pageSize":5,"pageNumber":1}'
A successful HTTP response is as follows:
{
"errMessage": "",
"success": true,
"responseData": [
{
"userName": "Bob",
"birthday": "2000-01-01",
"email": "bob@inc.com"
},
{
"userName": "Bob",
"birthday": "2001-01-01",
"email": "bob1@inc.com"
},
{
"userName": "Bob",
"birthday": "2002-01-01",
"email": "bob2@inc.com"
},
{
"userName": "Bob",
"birthday": "2003-01-01",
"email": "bob3@inc.com"
},
{
"userName": "Bob",
"birthday": "2004-01-01",
"email": "bob4@inc.com"
}
],
"totalCount": 5
}
3. Send Large File Notary
If notary data is saved in files, users can add fields with the type of File to save time. Business View supports file notaries and generates File notary APIs. Users need to set up the large file configuration in the application.properties file.
RESTful URL: api/{categoryName}
HTTP Method: POST
Request parameters.
Based on the definition of the category, submit a complete category.
Data structure of return value
RESPONSE
Parameter | Datatype | Is mandatory | Specification |
---|---|---|---|
responseData | string | no | Transaction hash |
success | bool | yes | Request is successful or not |
errMessage | string | no | Error message |
Assume that we have Data Classification Configuration in our schema.txt as below.
CertFile {
// picture of the certificate, must not be null
File image;
// text of the certificate, must not be null
File text;
// name of the certificate, must not be null
String name;
}
The URL path of the API is http://{your_server_ip}:8080/api/certFile.
Add HTTP Request Headers: Content-Type:multipart/form-data , HTTP Request Body is defined based on the definition of CertFile, as shown below.
Test the API with curl.
curl -X POST \
http://{your_server_ip}:8080/api/certFile \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F image=@/home/file/cert_image.pgn \
-F text=@/home/file/cert_text.txt \
-F 'name=my_file'
A successful HTTP response is as follows:
{
"errMessage" : "",
"responseData": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c",
"success" : true,
}
4. Query large file notaries
This API is automatically generated based on Data Classifications, one API for each category. The non-file fields of the category and the transaction hash can be used as the key to query transactions that meet the criteria.
RESTful URL: api/{categoryName}GetFiles
HTTP Method: POST
Request parameters
Parameter | Datatype | Is mandatory | Specification |
---|---|---|---|
key | string | no | Key of the query criteria |
value | string | no | Value of the query criteria |
pageSize | int | no | Page size of the return data, less than 100 |
pageNumber | int | no | Page number of the return data, starts with 1 |
Data structure of return value
The HTTP Response Headers of this API is Content-Type:application/zip, the HTTP Response Body contains a zip data stream, including all files that meet the criteria.
The following is a sample. We use the category CertFile described in API 3, the URL path would be http://{your_server_ip}:8080/api/certFileGetFiles .
Add HTTP Request Headers: Content-Type:application/json , and set the HTTP Request Body based on the definition of API. Note that the fields with type of File cannot be the key. Assume that we are querying data and the name is my_file with a page size of 5 and page number of 1, the HTTP Request Body is shown below.
{
"key":"name",
"value":"my_file",
"pageSize":5,
"pageNumber":1
}
Test the API with curl:
curl -X POST \
http://{your_server_ip}:8080/api/certFileGetFiles \
-H 'Content-Type: application/json' \
-d '{"key":"name","value":"my_file","pageSize":5,"pageNumber":1}' >> output-file.zip
The files meet the criteria can be found after unzipping output-file.zip.
5. Get information of transactions
Get information of transactions based on page number and page size.
RESTful URL: api/transactions
HTTP Method: GET
Request parameters
Parameter | Datatype | Is mandatory | Specification |
---|---|---|---|
pageSize | int | no | Page size of the return data, less than 100 |
pageNumber | int | no | Page number of the return data, starts with 1 |
Data structure of return value
RESPONSE
Parameter | Datatype | Is mandatory | Specification |
---|---|---|---|
responseData | list | no | Data of transactions, returns null when no transactions meets the criteria |
success | bool | yes | Request is successful or not |
errMessage | string | no | Error message |
totalCount | int | no | The length of responseData |
TransDetail data structure
Parameter | Datatype | Is mandatory | Specification |
---|---|---|---|
txHash | string | yes | Transaction hash |
type | int | yes | Notary type |
category | int | no | Category Id |
height | int | yes | Block height of the transaction |
blockHash | string | yes | Block hash of the transaction |
blockVersion | int | yes | Version number of the transaction |
createTime | string | yes | Create time |
referenceCount | int | no | Reference count |
content | string | no | The notary content |
link | string | no | The notary link |
contentHash | string | no | Hash value of the notary content |
nonce | string | no | Random nonce when encrypting data |
encryptContent | string | no | The encrypted notary content |
keyName | string | no | The name of the encrypt key |
keyWrap | string | no | Key wrap of the encrypt key |
The following is a sample. Assume that the page size is 5 and the page number is 1, then the URL path of the API call is http://{your_server_ip}:8080/api/transactions?pageSize=1&pageNumber=5.
Test the API with curl:
curl -X GET \
'http://{your_server_ip}:8080/api/transactions?pageSize=1&pageNumber=5'
A successful HTTP response is as follows:
{
"errorMsg": "",
"totalCount": 2,
"responseData": [
{
"txHash": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c",
"type": 4,
"category": -1,
"height": 273852,
"blockHash": "9c3308565b934ec65a312b423b1697a955bc0912baf1f80b1a043097e1674c36",
"blockVersion": 1,
"createTime": "2018-05-30T03:35:50.000Z",
"referenceCount": 0,
"content": "eyJjZXJ0Tm8iOiJiNTc3ZTFhZmE0YWUwOWY3Zjk4YjAzMWMyOTJmMmEyOWE3NjE3NzlmOTEzNTZlZjk4M2Q2NjdmODAwYjBlNThlIiwidmVyc2lvbiI6MSwiaXNDZXJ0QWN0aXZlIjp0cnVlLCJhY3RpdmVCaXoiOjEsImNpZCI6IjEwMCJ9",
"link": null,
"contentHash": null,
"nonce": null,
"encryptContent": null,
"keyName": null,
"keyWrap": null
},
{
"txHash": "1ed22275a0f0f425c5556efc580b86582189b1628cfbab78bbae9e1fe8ca4927",
"type": 4,
"category": 65537,
"height": 212282,
"blockHash": "91da9bd833b2e0c7bd68215d3b41bf7c0d016f0b0320bedab05d0cc8e0b67335",
"blockVersion": 1,
"createTime": "2018-05-29T12:43:57.000Z",
"referenceCount": 0,
"content": "rO0ABXNyADVjb20uYWxpcGF5Lm15Y2hhaW4uc2RrLnBsdXMuZW50aX",
"link": null,
"contentHash": null,
"nonce": null,
"encryptContent": null,
"keyName": null,
"keyWrap": null
}
],
"success": true
}
6. Get information of transactions by txHash
Get information of transactions by txHash.
RESTful URL: api/transactions/{txhash}
HTTP Method: GET
Request parameters
Parameter | Datatype | Is mandatory | Specification |
---|---|---|---|
txHash | hash hex string | yes | Transaction hash |
Returns json text
RESPONSE
Similar to the response of API 5, the only difference is that the value of totalCount must be be 0 or 1.
The following is a sample. Assume that we are querying a transaction with txHash equals to 1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c, we can call the API with curl:
curl -X GET \
'http://{your_server_ip}:8080/api/transactions/1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c'
A successful HTTP response is as follows:
{
"errMessage" : "",
"totalCount" : 1,
"responseData" : [
{
"txHash": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c",
"type": 4,
"category": -1,
"height": 273852,
"blockHash": "9c3308565b934ec65a312b423b1697a955bc0912baf1f80b1a043097e1674c36",
"blockVersion": 1,
"createTime": "2018-05-30T03:35:50.000Z",
"referenceCount": 0,
"content": "eyJjZXJ0Tm8iOiJiNTc3ZTFhZmE0YWUwOWY3Zjk4YjAzMWMyOTJmMmEyOWE3NjE3NzlmOTEzNTZlZjk4M2Q2NjdmODAwYjBlNThlIiwidmVyc2lvbiI6MSwiaXNDZXJ0QWN0aXZlIjp0cnVlLCJhY3RpdmVCaXoiOjEsImNpZCI6IjEwMCJ9",
"link": null,
"contentHash": null,
"nonce": null,
"encryptContent": null,
"keyName": null,
"keyWrap": null
}
],
"success" : true,
}
7. Send notary to Blockchain with other types
Send a transaction to the blockchain with notary type other than the default type ContentOnlyNotaryPayloadDO.
RESTful URL: api/transactions
HTTP Method: POST
Request parameters
TransDetail
Parameter | Datatype | Is mandatory | Specification |
---|---|---|---|
type | int | yes | Notary type, check the note below |
category | int | no | Category Id |
content | string | no | The notary content |
link | string | no | The notary link |
contentHash | string | no | Hash value of the notary content |
nonce | string | no | Random nonce when encrypting data |
encryptContent | string | no | The encrypted notary content |
keyName | string | no | The name of the encrypt key |
keyWrap | string | no | Key wrap of the encrypt key |
Note that this API supports the following notary types of Ant Blockchain. Please check the specifications of different notary types in Transaction models for attestation . The ContentOnlyNotaryPayloadDO is not supported in this API since it is our default notary type and has already been supported in API 1, 2, and 4.
Notary Type | Type Value | Specification |
---|---|---|
HashOnlyNotaryPayloadDO | 3 | Hash notary model |
LinkNotaryPayloadDO | 5 | Link notary model |
EncryptNotaryPayloadDO | 6 | Privacy notary model |
EncryptContentOnlyNotaryPayloadDO | 7 | Privacy notary model |
EncryptShareNotaryPayloadDO | 8 | Privacy sharing notary model |
ContentOnlyNotaryPayloadDO | Content notary model (not supported here) |
Returns json text
RESPONSE
Parameter | Datatype | Is mandatory | Specification |
---|---|---|---|
success | bool | yes | Request is successful or not |
errorMsg | string | no | Error message |
txHash | string | no | Transaction hash |
A successful HTTP response is as follows:
{
"errorMsg": "",
"txHash": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c",
"success": true
}