Oracle Blockchain Cloud Service — Invoke Chaincode by means of OBCS REST APIs

The previous blog posts introduced the OBCS - Oracle Blockchain Cloud Service as well as provided the steps on how to configure the Network Founder Instance and a Participant Organization instance.

We also explored how to perform the required Fabric network configurations, including the ones required for peers, channels, security and other components.

In complement, we also demonstrated how to perform the chaincode (smart contract) deployment and instantiation.

Now this this blog post provides the steps required to invoke the chaincode (smart contract) business methods by using the OBCS REST APIs.

You can check the official documentation and the available options regarding how you can invoke the OBCS REST APIs. However below we have the summarized steps you can use with some tips and details you have to pay attention to.

So without further ado, let’s explore how we can use the OBCS REST API in order to invoke smart contracts and interact with the Oracle Blockchain Cloud Service.

You can use the REST APIs to interact with your chaincode and the OBCS

The instructions below provide examples about security and transactions.

Below we first have the steps considering how you can authenticate a REST client against the service as well as how to check the OBC version, invoke transactions and read data from the Blockchain.

In order to perform the REST call, you have many choices as usual. You can use several different programming languages and the related REST client libraries, for example a Java REST API client like the one available in the Jersey libraries (JAX-RS). You can also use command line (CLI) tools such as curl for example.

There are also several browser plugins that you can use like Postman. In the examples

below we’ll use Postman as it simplifies the tasks as well as it can abstract you from the differences that might exist in different operating systems like the need for character scape tweaks, different encoding standards and others.

In order to perform the calls, you need to check and provide the URL for the OBCS REST Proxy You want to use.

Understand the format of resource URLs

https://<rest_server_url:port/restproxy#>/<resource-path

In order to get that for your Blockchain instance, go to the Nodes tab on the OBCS console, select the List View icon and then click copy the link from the related REST Proxy node.

Note that you have to repace the rest_server_url and port to target your own environment (OBCS instance with the related REST proxy). You can get the information about your proxy (restproxy1 in the URL below) from the Nodes tab on the OBCS instance console.

Below we have an example URL:

https://AB994E6349734C1889E379FAAD9BF0F8.blockchain.ocp.oraclecloud.com:443/restproxy1/

How to use the Postman tool to perform REST API calls against OBCS

You can use use curl, a command-line (CLI) tool.

The first call we’ll perform will be just a call to check the Oracle Blockchain Cloud Service version. Below we have what this call looks like in plain curl syntax. You need to provide your <user_name> as well as your <password> in the call below:

curl -u <YOUR_USER_ID>:<YOUR_PASSWORD> -X GEThttps://AB994E6349734C1889E379FAAD9BF0F8.blockchain.ocp.oraclecloud.com:443/restproxy1/bcsgw/rest/version

Provided that everything is correct, the version will be returned as a JSON response as shown below. That will allow you to validate your target REST proxy URL as well as your authentication details.

{"version":"v1.0"}

Security and authentication methods

Please check the security section of our OBCS documentation as per the links provided in the beginning of this guide in order to authenticate by using different methods.

Blockchain transactions — invocations

Let’s execute a call to add a Car as per the example chaincode we provided in the previous blog post.

Below we have what this call looks like in plain curl syntax and the following screenshots will show how to use Postman for the the same related call.

curl -u <YOUR_USER_ID>:<YOUR_PASSWORD> -H "Content-type:application/json" -X POST https://AB994E6349734C1889E379FAAD9BF0F8.blockchain.ocp.oraclecloud.com:443/restproxy1/bcsgw/rest/v1/transaction/invocation -d '{"channel":"default","chaincode":"carTrace","method":"initVehicle","args":["mer1000001", "mercedes", "c class", "1502688979", "ser1234", "mercedes", "false", "1502688979"],"chaincodeVer":"v1"}'

On Postman, configure the HTTP method as POST and provide the target URL as shown below.

Click the Authorization tab and select HTTP BASIC as the authentication method, then provide your username and password and click the Update Request button.

Then select the Headers tab, add an additional HTTP request header Content-Type and the value of it as application/json.

Now, select the Body tab, select the raw radio button option and provide the body payload as JSON from the original curl call provided above, as shown below:

You can now click the Send button, provided that everything is OK the call will be performed and you will receive an HTTP 200 OK as the HTTP response status code.

Besides, the response body as JSON will provide a returnCode with the value as Success as well as the txid attribute will provide the effective transaction ID on the Blockchain side.

You can also perform calls to add more properties as below:

curl -u <YOUR_USER_ID>:<YOUR_PASSWORD> -H "Content-type:application/json" -X POST https://AB994E6449134C1889E379FAAD9BF0F8.blockchain.ocp.oraclecloud.com:443/restproxy1/bcsgw/rest/v1/transaction/invocation -d '{"channel":"default","chaincode":"carTrace","method":"initVehicle","args":["maz1000001", "mazda", "mazda 6", "1502688979", "ser1235", "mazda", "false", "1502688979"],"chaincodeVer":"v1"}'

Blockchain transactions — queries

The related REST API call in curl is shown below, followed by the related Postman screenshot.

curl -u <YOUR_USER_ID>:<YOUR_PASSWORD> -H "Content-type:application/json" -X POST https://AB994E6449134C1889E379FAAD9BF0F8.blockchain.ocp.oraclecloud.com:443/restproxy1/bcsgw/rest/v1/transaction/query -d
'{"channel":"default","chaincode":"carTrace","method":"readVehicle","args":["mer1000001"],"chaincodeVer":"v1"}'

The request configuration steps in Postman as the same ones as before. You just need to update the URL as well as the HTTP body payload message as JSON to be in accordance with the REST API call above. Below we have the screenshot as per the example:

When you click send, a query transaction will be executed and the result will be shown as above, with a returnCode of Success and the resulting data payload for the respective car we searched for.

Blockchain transactions — dashboard

Give it a try! Get Started with Oracle Cloud for Free!

Azure Developer Relations Lead @ Microsoft. Invite me to speak about #Blockchain #IoT #AI #Java #Python #EmergingTechnologies #DevRel 🥑