Help Center > > API Reference> Calling APIs

Calling APIs

Updated at: Jun 19, 2019 GMT+08:00

BCS provides RESTful APIs. REST-based web services are organized into resources. Each resource is identified by one or more Uniform Resource Identifiers (URIs). An application 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 resource path, that is, the API access path.

APIs use HTTP as the transmission protocol. Requests/Responses are transmitted by 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 URI

A 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 programming languages or frameworks require the request URI to be separately transmitted, rather than being conveyed in a request message.

Table 1 Parameters in a URI

Parameter

Description

URI-scheme

Protocol used to transmit requests. BCS APIs use HTTPS.

Endpoint

IP address and port number of the server bearing the RESTful service endpoint. To obtain the IP address, choose More > View Service Details in the Operation column of the purchased service listed on the Service Management page. The port number is fixed at 32621.

resource-path

API access path for performing a specified operation. Only the chaincode invoking API is available now. Its path is fixed at /v1/chaincode/operation.

query-string

Not used.

Request Header

A 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 invoking RESTful API supports the following method.
Table 2 HTTP

Method

Description

PUT

Requests the server to update specified resources.

  • The following table lists the request header parameters customized for the chaincode invoking RESTful API.
Table 3 Customized header parameters

Parameter

Description

Mandatory

x-bcs-signature-sign

Signature of the chaincode invoking request message body

Yes

x-bcs-signature-method

Encryption type, which is fixed at SW now.

Yes

x-bcs-signature-sign-gzip

Indication of whether GZIP compression is enabled. 0 indicates disabling, and 1 indicates enabling.

Yes

NOTE:

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

Request Body

See BCS APIs.

Response Header

HTTP status code. A status code consists of three digits (2xx to 5xx). 2xx indicates a success response. 4xx and 5xx indicate failure responses. The status code returned can also be defined by the service.

Response Body

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

Initiating a Request

A request can be initiated by using either of the following methods:

  • cURL

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

  • Code

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

Did you find this page helpful?

Submit successfully!

Thank you for your feedback. Your feedback helps make our documentation better.

Failed to submit the feedback. Please try again later.

Which of the following issues have you encountered?







Please complete at least one feedback item.

Content most length 200 character

Content is empty.

OK Cancel