All Products
Search
Document Center

API specification

Last Updated: Jul 23, 2019

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:

  1. 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.

  2. 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.

  3. 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:

  1. 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.

  2. 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.

  1. GuestInfo {
  2. // name, cannot be null。
  3. String userName;
  4. // email address, cannot be null。
  5. String email;
  6. // birthday, cannot be null
  7. String birthday
  8. }

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.

  1. {
  2. "userName":"Kate",
  3. "email":"kate@163.com",
  4. "birthday":"20180101"
  5. }

Test the API with curl.

  1. curl -X POST \
  2. http://{your_server_ip}:8080/api/certFile \
  3. -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  4. -F 'userName=Kate' \
  5. -F 'email=kate@163.com' \
  6. -F 'birthday=20180101'

A successful HTTP response is as follows:

  1. {
  2. "errMessage" : "",
  3. "responseData": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c"
  4. "success" : true,
  5. }

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.

  1. {
  2. "key":"userName",
  3. "value":"Bob",
  4. "pageSize":5,
  5. "pageNumber":1
  6. }

Test the API with curl.

  1. curl -X POST \
  2. http://{your_server_ip}:8080/api/guestInfoGet \
  3. -H 'Content-Type: application/json' \
  4. -d '{"key":"userName","value":"Bob","pageSize":5,"pageNumber":1}'

A successful HTTP response is as follows:

  1. {
  2. "errMessage": "",
  3. "success": true,
  4. "responseData": [
  5. {
  6. "userName": "Bob",
  7. "birthday": "2000-01-01",
  8. "email": "bob@inc.com"
  9. },
  10. {
  11. "userName": "Bob",
  12. "birthday": "2001-01-01",
  13. "email": "bob1@inc.com"
  14. },
  15. {
  16. "userName": "Bob",
  17. "birthday": "2002-01-01",
  18. "email": "bob2@inc.com"
  19. },
  20. {
  21. "userName": "Bob",
  22. "birthday": "2003-01-01",
  23. "email": "bob3@inc.com"
  24. },
  25. {
  26. "userName": "Bob",
  27. "birthday": "2004-01-01",
  28. "email": "bob4@inc.com"
  29. }
  30. ],
  31. "totalCount": 5
  32. }

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.

  1. CertFile {
  2. // picture of the certificate,must not be null。
  3. File image;
  4. // text of the certificate,must not be null。
  5. File text;
  6. // name of the certificate,must not be null
  7. String name;
  8. }

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.

  1. curl -X POST \
  2. http://{your_server_ip}:8080/api/certFile \
  3. -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  4. -F image=@/home/file/cert_image.pgn \
  5. -F text=@/home/file/cert_text.txt \
  6. -F 'name=my_file'

A successful HTTP response is as follows:

  1. {
  2. "errMessage" : "",
  3. "responseData": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c"
  4. "success" : true,
  5. }

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.

  1. {
  2. "key":"name",
  3. "value":"my_file",
  4. "pageSize":5,
  5. "pageNumber":1
  6. }

Test the API with curl:

  1. curl -X POST \
  2. http://{your_server_ip}:8080/api/certFileGetFiles \
  3. -H 'Content-Type: application/json' \
  4. -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.

files_dowloaded

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:

  1. curl -X GET \
  2. 'http://{your_server_ip}:8080/api/transactions?pageSize=1&pageNumber=5'

A successful HTTP response is as follows:

  1. {
  2. "errorMsg": "",
  3. "totalCount": 2,
  4. "responseData": [
  5. {
  6. "txHash": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c",
  7. "type": 4,
  8. "category": -1,
  9. "height": 273852,
  10. "blockHash": "9c3308565b934ec65a312b423b1697a955bc0912baf1f80b1a043097e1674c36",
  11. "blockVersion": 1,
  12. "createTime": "2018-05-30T03:35:50.000Z",
  13. "referenceCount": 0,
  14. "content": "eyJjZXJ0Tm8iOiJiNTc3ZTFhZmE0YWUwOWY3Zjk4YjAzMWMyOTJmMmEyOWE3NjE3NzlmOTEzNTZlZjk4M2Q2NjdmODAwYjBlNThlIiwidmVyc2lvbiI6MSwiaXNDZXJ0QWN0aXZlIjp0cnVlLCJhY3RpdmVCaXoiOjEsImNpZCI6IjEwMCJ9",
  15. "link": null,
  16. "contentHash": null,
  17. "nonce": null,
  18. "encryptContent": null,
  19. "keyName": null,
  20. "keyWrap": null
  21. },
  22. {
  23. "txHash": "1ed22275a0f0f425c5556efc580b86582189b1628cfbab78bbae9e1fe8ca4927",
  24. "type": 4,
  25. "category": 65537,
  26. "height": 212282,
  27. "blockHash": "91da9bd833b2e0c7bd68215d3b41bf7c0d016f0b0320bedab05d0cc8e0b67335",
  28. "blockVersion": 1,
  29. "createTime": "2018-05-29T12:43:57.000Z",
  30. "referenceCount": 0,
  31. "content": "rO0ABXNyADVjb20uYWxpcGF5Lm15Y2hhaW4uc2RrLnBsdXMuZW50aX",
  32. "link": null,
  33. "contentHash": null,
  34. "nonce": null,
  35. "encryptContent": null,
  36. "keyName": null,
  37. "keyWrap": null
  38. }
  39. ],
  40. "success": true
  41. }

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:

  1. curl -X GET \
  2. 'http://{your_server_ip}:8080/api/transactions/1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c'

A successful HTTP response is as follows:

  1. {
  2. "errMessage" : "",
  3. "totalCount" : 1,
  4. "responseData" : [
  5. {
  6. "txHash": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c",
  7. "type": 4,
  8. "category": -1,
  9. "height": 273852,
  10. "blockHash": "9c3308565b934ec65a312b423b1697a955bc0912baf1f80b1a043097e1674c36",
  11. "blockVersion": 1,
  12. "createTime": "2018-05-30T03:35:50.000Z",
  13. "referenceCount": 0,
  14. "content": "eyJjZXJ0Tm8iOiJiNTc3ZTFhZmE0YWUwOWY3Zjk4YjAzMWMyOTJmMmEyOWE3NjE3NzlmOTEzNTZlZjk4M2Q2NjdmODAwYjBlNThlIiwidmVyc2lvbiI6MSwiaXNDZXJ0QWN0aXZlIjp0cnVlLCJhY3RpdmVCaXoiOjEsImNpZCI6IjEwMCJ9",
  15. "link": null,
  16. "contentHash": null,
  17. "nonce": null,
  18. "encryptContent": null,
  19. "keyName": null,
  20. "keyWrap": null
  21. }
  22. ],
  23. "success" : true,
  24. }

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:

  1. {
  2. "errorMsg": "",
  3. "txHash": "1d33029f014096d98f2265222d5aef3bebac5de00aadf0a5f370256be243a48c",
  4. "success": true
  5. }