All Products
Search
Document Center

:API specification

Last Updated:Aug 19, 2022

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.

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.

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:

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

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
}