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

by Juarez Junior

Introduction

The previous blog posts introduced the OBCS - Oracle Blockchain Cloud Service as well as providing 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 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 Oracle Blockchain Cloud Service has a REST API that can be used to interact with your chaincode. Here you can get the list of OBCS API REST Endpoints so you can understand what can be performed with them. Not only calls to smart contracts but also many operational and management tasks can now be performed by using the REST APIs.

The instructions below provide examples of 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.

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 abstracts 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

In order to use the REST APIs, you need to determine the URL for your instance. The structure of the REST URL requests is described in Send Requests. The basic URL template is shown below:

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 replace 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

We will use Postman. It’s a REST tool you can install as a Google Chrome plug-in for example or as a standalone tool. It’s up to you to decide which one is the best option for you. Install and start Postman.

You can 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 GET
https://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

In relation to security, this guide just provides an example of how to use standard HTTP BASIC authentication, however other authentication methods are also supported such as OAuth 2.0 and Oracle Identity Cloud Service federation.

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

Blockchain transactions — invocations

So now we can perform our first Blockchain transaction invocation.

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 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 of 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

You can also query the Blockchain so that you can get the information regarding the transactions and the related property in the previous example.

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

As you may know, you can use the Dashboard in order to inspect the related transaction metrics and additional information as usual.

Wrapping-up

That’s our final post in this series! I hope you liked exploring Blockchain with Oracle!

Oracle Developers and Oracle OCI Free Tier

Join our Oracle Developers channel on Slack to discuss Microservices, Java, JDBC, Oracle Cloud Infrastructure, Oracle Database, and other topics!

Build, test, and deploy your applications on Oracle Cloud — for free! Get access to OCI Cloud Free Tier!