API Reference - HUAWEI CLOUDCalling APIs BCS provides RESTful APIs. REST-based web services are organized into resources. Each resource is identified by one or more Uniform Resource

Blockchain Service

API Reference

Issue 01

Date 2020-05-29

HUAWEI TECHNOLOGIES CO., LTD.

Copyright © Huawei Technologies Co., Ltd. 2020. All rights reserved.

No part of this document may be reproduced or transmitted in any form or by any means without priorwritten consent of Huawei Technologies Co., Ltd. Trademarks and Permissions

and other Huawei trademarks are trademarks of Huawei Technologies Co., Ltd.All other trademarks and trade names mentioned in this document are the property of their respectiveholders. NoticeThe purchased products, services and features are stipulated by the contract made between Huawei andthe customer. All or part of the products, services and features described in this document may not bewithin the purchase scope or the usage scope. Unless otherwise specified in the contract, all statements,information, and recommendations in this document are provided "AS IS" without warranties, guaranteesor representations of any kind, either express or implied.

The information in this document is subject to change without notice. Every effort has been made in thepreparation of this document to ensure accuracy of the contents, but all statements, information, andrecommendations in this document do not constitute a warranty of any kind, express or implied.

Issue 01 (2020-05-29) Copyright © Huawei Technologies Co., Ltd. i

Contents

1 Before You Start....................................................................................................................... 11.1 Overview.................................................................................................................................................................................... 11.2 Endpoints....................................................................................................................................................................................11.3 Constraints................................................................................................................................................................................. 11.4 Concepts..................................................................................................................................................................................... 2

2 Calling APIs............................................................................................................................... 4

3 BCS APIs..................................................................................................................................... 73.1 Chaincode Invoking API........................................................................................................................................................ 7

4 Appendix..................................................................................................................................104.1 Status Code............................................................................................................................................................................. 104.2 Error Code................................................................................................................................................................................104.3 Obtaining Account and Project IDs................................................................................................................................ 10

Blockchain ServiceAPI Reference Contents

Issue 01 (2020-05-29) Copyright © Huawei Technologies Co., Ltd. ii

1 Before You Start

1.1 OverviewWelcome to Blockchain Service API Reference. Blockchain Service (BSC) helps youquickly deploy, manage, and maintain a blockchain network on HUAWEI CLOUD,reducing the threshold for using blockchain. Using this service, you can focus onthe development and innovation of your own business and quickly migrate yourbusiness to blockchains.

This document describes how to use application programming interfaces (APIs) toperform operations on chaincodes, such as querying and invoking a chaincode.

If you plan to access a BCS service through an API, ensure that you understand thebasics including concepts of BCS.

1.2 EndpointsAn endpoint is the request address for calling an API. Endpoints vary depending onservices and regions. For the endpoints of all services, see Regions and Endpoints.

A BCS endpoint specifies the IP address and port number of the server bearing theRESTful service endpoint. To obtain the IP address, choose More > View ServiceDetails in the Operation column of the purchased service listed on the ServiceManagement page. The port number is fixed at 32621.

1.3 ConstraintsTo use the RESTful APIs of BCS, you need to buy a BCS service and download theuser certificate.

Buying BCS ServiceSee Blockchain Service User Guide.

Blockchain ServiceAPI Reference 1 Before You Start

Issue 01 (2020-05-29) Copyright © Huawei Technologies Co., Ltd. 1

https://developer.huaweicloud.com/en-us/endpoint

Downloading the User Certificate

You need to download the user certificate that is configured in BCS to call theAPIs.

Step 1 Log in to the HUAWEI CLOUD BCS console.

Step 2 Choose Service Management. You can view the list of purchased BCS services.

Step 3 Expand a service, and download the user certificate of your organization.

Step 4 Decompress the certificate. The decompressed directory structure is as illustratedin the following figure. The private key of the organization is stored in keystore,and the user certificate (public key) in signcerts.

----End

1.4 Concepts● Account

An account is generated after you register with HUAWEI CLOUD. An accounthas full access permissions for all the resources and cloud services under theaccount. It can reset user passwords and grant users permissions. The accountis a payment entity, which should not be used directly to perform routinemanagement. To ensure account security, create IAM users and grant thempermissions for routine management.

● IAM user

An IAM user is created by an account in IAM to use cloud services. Each IAMuser has its own identity credentials (password and access keys).



An IAM user can view the account ID and user ID on the My Credentialspage of the management console. API authentication requires suchinformation as the account name, IAM user name, and password.

● RegionA region is a geographic area in which cloud resources are deployed.Availability zones (AZs) in the same region can communicate with each otherover an intranet, while AZs in different regions are isolated from each other.Deploying cloud resources in different regions can better suit certain userrequirements or comply with local laws or regulations.

● AZAn AZ comprises of one or more physical data centers equipped withindependent ventilation, fire, water, and electricity facilities. Computing,network, storage, and other resources in an AZ are logically divided intomultiple clusters. AZs within a region are interconnected using high-speedoptical fibers to allow you to build cross-AZ high-availability systems.

● ProjectA project corresponds to a HUAWEI CLOUD region. Default projects aredefined to a group and have physically isolated resources (includingcomputing, storage, and network resources) across regions. Users can begranted permissions in a default project to access all resources in the regionassociated with the project. If you need more refined access control, createsubprojects under a default project and purchase resources in subprojects.Then you can assign users the permissions required to access only theresources in the specific subprojects.

Figure 1-1 Project isolating model



2 Calling APIs

BCS provides RESTful APIs. REST-based web services are organized into resources.Each resource is identified by one or more Uniform Resource Identifiers (URIs). Anapplication accesses a resource based on the resource's Uniform Resource Locator(URL).

A URL is usually in the format of "https://Endpoint/uri". uri indicates the resourcepath, that is, the API access path.

APIs use HTTP as the transmission protocol. Requests/Responses are transmittedby using JSON packets, with the media type represented by Application/json.

A RESTful API request or response consists of the following parts:

● Request URI● Request header● Request body● Response header● Response body

Request URIA request URI is in the following format:

{URI-scheme} :// {Endpoint} / {resource-path} ? {query-string}

Although a request URI is included in a request header, most programminglanguages or frameworks require the request URI to be separately transmitted,rather than being conveyed in a request message.

Table 2-1 Parameters in a URI

Parameter Description

URI-scheme Protocol used to transmit requests. BCS APIs use HTTPS.

Blockchain ServiceAPI Reference 2 Calling APIs


Parameter Description

Endpoint IP address and port number of the server bearing theRESTful service endpoint. To obtain the IP address, chooseMore > View Service Details in the Operation column ofthe purchased service listed on the Service Managementpage. The port number is fixed at 32621.

resource-path API access path for performing a specified operation. Onlythe chaincode invoking API is available now. Its path is fixedat /v1/chaincode/operation.

query-string Not used.

Request HeaderA request header consists of an HTTP method and custom fields.

● HTTP-based request methods, which are also called operations or actions,specify the type of operations that you are requesting. The chaincode invokingRESTful API supports the following method.

Table 2-2 HTTP

Method Description

PUT Requests the server to update specified resources.

● The following table lists the request header parameters customized for thechaincode invoking RESTful API.

Table 2-3 Customized header parameters

Parameter Description Mandatory

x-bcs-signature-sign Signature of the chaincodeinvoking request message body

Yes

x-bcs-signature-method Encryption type, which is fixed atSW now.

Yes

x-bcs-signature-sign-gzip Indication of whether GZIPcompression is enabled. 0indicates disabling, and 1indicates enabling.

Yes



X-bcs-signature-sign: To ensure that only authorized invocation entities can invokechaincodes, the user private key (downloaded by following Downloading the UserCertificate) and the ECDSA encryption method must be used to encrypt and sign theSHA256 hash of the entire request body. The value of x-bcs-signature-sign is the encryptedand signed hash.

Request BodySee BCS APIs.

Response HeaderHTTP status code. A status code consists of three digits (2xx to 5xx). 2xx indicatesa success response. 4xx and 5xx indicate failure responses. The status codereturned can also be defined by the service.

Response BodyA response body conveys information other than the response header and isusually sent in a structured format (for example, JSON or XML) defined by theresponse header parameter Content-type.

Initiating a RequestA request can be initiated by using either of the following methods:

● cURLcURL is a command line tool used to perform URL operations and transmitinformation. cURL acts as an HTTP client that can send HTTP requests to aserver and receive response messages. cURL is suitable for use in API tuningscenarios. For more information about cURL, visit https://curl.haxx.se/.

● CodeYou can call an API using code to assemble, send, and process requests.



https://curl.haxx.se/

3 BCS APIs

3.1 Chaincode Invoking API

FunctionThis API is used to invoke and query the instantiated chaincodes of deployed BCSservices.

URIPOST /v1/chaincode/operation

Request Message

Table 3-1 Message fields

Parameter Mandatory

Type Description

channelId Yes String Channel ID in a blockchain.

chaincodeId Yes String Chaincode ID.

chaincodeVersion No String Chaincode version.

userId Yes String User ID issued by the organizationCA. Currently, the default valuegenerated for BCS is User1.

orgId Yes String Organization ID in a blockchain.

Blockchain ServiceAPI Reference 3 BCS APIs


Parameter Mandatory

Type Description

orgPeers Yes String A character string consisting of theorganization ID and domain nameof each peer in an organization.The format is as follows:[{"orgId":"7258adda1803f4137eff4813e7aba323018200c5","peerDomainName":"peer-7258adda1803f4137eff4813e7aba323018200c5-0.peer-7258adda1803f4137eff4813e7aba323018200c5.default.svc.cluster.local"}]

opmethod Yes String Purpose, that is, to invoke orquery chaincodes.

args Yes String Arguments, for example,["Invoke", "a", "b", "1"]

timestamp Yes String For example,2018-10-31T17:28:16+08:00.

cert Yes String User certificate file, which isuploaded in the form of acharacter string.

For details on how to obtain the values of the preceding parameters, see ChaincodeManagement and Block Browser.

● On the Chaincode Management page, click in front of a chaincode to view itsdetails, including the version, installation, and instantiation information.

● On the Block Browser page, select a channel to view real-time blockchain information,including the block quantity, transaction quantity, block details, transaction details,performance, and peer statuses.

● To ensure transaction security, you must use the private key in the Fabric user certificate(downloaded by following instructions in Downloading the User Certificate) to signthe request body. Currently, only the ECDSA encryption method is supported. Otherencryption algorithms such as Chinese cryptographic algorithms are not supported.Then, place the signature result in the x-bcs-signature-sign field in the request header.

Response Message● If opmethod is invoke, the transactionID encrypted and encoded using

Base64 is returned.● If opmethod is query, the query result returned by the chaincode is also

encrypted and encoded using Base64.

ExampleInvoking a chaincode



https://support.huaweicloud.com/en-us/usermanual-bcs/bcs_usermanual_0003.html



● Example request{ "channelId": "testchannel", "chaincodeId": "zmmcode", "chaincodeVersion": "1.0", "userId": "User1", "orgId": "7258adda1803f4137eff4813e7aba323018200c5", "orgPeers": "[{\"orgId\":\"7258adda1803f4137eff4813e7aba323018200c5\",\"peerDomainName\":\"peer-7258adda1803f4137eff4813e7aba323018200c5-0.peer-7258adda1803f4137eff4813e7aba323018200c5.default.svc.cluster.local\"}]", "opmethod": "invoke", "args": "[\"invoke\",\"a\",\"b\",\"1\"]", "timestamp": "2018-10-31T17:28:16+08:00", "cert": "-----BEGIN CERTIFICATE-----\nMIIDBzCCAq2gAwIBAgIQEXPZlMsReamxVtVNnKwCCzAKBggqhkjOPQQDAjCCAQQx\nDjAMBgNVBAYTBUNISU5BMRAwDgYDVQQIEwdCRUlKSU5HMRAwDgYDVQQHEwdCRUlK\nSU5HMXkwdwYDVQQKE3A3MjU4YWRkYTE4MDNmNDEzN2VmZjQ4MTNlN2FiYTMyMzAx\nODIwMGM1LnBlZXItNzI1OGFkZGExODAzZjQxMzdlZmY0ODEzZTdhYmEzMjMwMTgy\nMDBjNS5kZWZhdWx0LnN2Yy5jbHVzdGVyLmxvY2FsMVMwUQYDVQQDE0pjYS5wZWVy\nLTcyNThhZGRhMTgwM2Y0MTM3ZWZmNDgxM2U3YWJhMzIzMDE4MjAwYzUuZGVmYXVs\ndC5zdmMuY2x1c3Rlci5sb2NhbDAeFw0xODEwMzAwMjQ5MjZaFw0yODEwMjcwMjQ5\nMjZaMIG1MQ4wDAYDVQQGEwVDSElOQTEQMA4GA1UECBMHQkVJSklORzEQMA4GA1UE\nBxMHQkVJSklORzF/MH0GA1UEAwx2VXNlcjFANzI1OGFkZGExODAzZjQxMzdlZmY0\nODEzZTdhYmEzMjMwMTgyMDBjNS5wZWVyLTcyNThhZGRhMTgwM2Y0MTM3ZWZmNDgx\nM2U3YWJhMzIzMDE4MjAwYzUuZGVmYXVsdC5zdmMuY2x1c3Rlci5sb2NhbDBZMBMG\nByqGSM49AgEGCCqGSM49AwEHA0IABPMrzoJL/MHeSFPFOJWLqnJ0sqB0it7wDIOq\n+eTSvvPpGk1BIDmb2n13K5V04RO8xNezDQ7I6rW4LF2elq14eH+jTTBLMA4GA1Ud\nDwEB/wQEAwIHgDAMBgNVHRMBAf8EAjAAMCsGA1UdIwQkMCKAIFBXQ5TC4acFeTlT\nJuDZg62XkXCdnOfvbejSeKI2TXoIMAoGCCqGSM49BAMCA0gAMEUCIQCadHIKl0Mk\nYn0WZizyDZYR4rT2q0nzjFaiW+YfV5FBjAIgNalKUe3rIwXJvXORV4ZXurEua2Ag\nQmhcjRnVwPTjpTE=\n-----END CERTIFICATE-----\n"}

● Example response After invoke the count of a is 188 b is 262

Status CodeFor details, see Status Code.



4 Appendix

4.1 Status Code

Table 4-1 Status code

Status Code Description

200 OK The request has succeeded.

4.2 Error CodeIf an error occurs in the API, no result is returned. You can locate the error causebased on the error codes of each API. If the invocation fails, an HTTP status code4xx or 5xx is returned. The returned message body contains the specific error codeand information. If you fail to locate the cause of an error, contact customerservice and provide the error code, so that we can help you solve the problem assoon as possible.

4.3 Obtaining Account and Project IDs

Obtaining Account and Project IDs from the Console

Account and project IDs are required for some URLs when an API is called. You canperform the following operations to obtain the IDs:

1. Log in to the management console.

Blockchain ServiceAPI Reference 4 Appendix


2. Click the username and select My Credential from the drop-down list.

3. On the My Credential page, view the account and project IDs.

If there are multiple projects in one region, expand Region and view sub-projectIDs in the Project ID column.

Obtaining a Project ID by Calling an APIThe API for obtaining a project ID is GET https://{Endpoint}/v3/projects/, where{Endpoint} indicates the IAM endpoint.

The following is an example response. The value of id in the projects section isthe project ID.

{ "projects": [ { "domain_id": "65382450e8f64ac0870cd180d14e684b", "is_domain": false, "parent_id": "65382450e8f64ac0870cd180d14e684b", "name": "cn-north-4", "description": "", "links": { "next": null, "previous": null, "self": "https://www.example.com/v3/projects/a4a5d4098fb4474fa22cd05f897d6b99" }, "id": "a4a5d4098fb4474fa22cd05f897d6b99", "enabled": true } ], "links": { "next": null, "previous": null, "self": "https://www.example.com/v3/projects" }}

Blockchain ServiceAPI Reference 4 Appendix


Documents

API Reference - HUAWEI CLOUDCalling APIs BCS provides RESTful APIs. REST-based web services are organized into resources. Each resource is identified by one or more Uniform Resource