Getting to know Oracle Autonomous Blockchain Cloud Service — Part 3— Expose and run deployed sample smart contracts via REST proxy
In the previous article, you have invoked the samples you installed and instantiated against a channel(boaventuraorderer) by using the sample page. However, in the real world, you will be accessing your smart contracts(chaincodes) as APIs. This is where the REST gateway comes to the picture. Then, in this article, you will be setting up chaincodes to be exposed as REST APIs through the OABCS REST proxy and then will play with some of the key REST APIs available in Oracle Autonomous Blockchain Cloud Service to invoke smart contracts.
Getting Started with OABCS REST proxy
In order to access smart contracts(chaincodes in OABCS) through the REST proxy, you need to perform the following steps:
1. Go to the Nodes tab at http://<yourOABCSHostAddress>:<yourOABCSPort>/?root=node
2. Highlight the gateway row and click on the menu icon on the right edge of the row, then select Edit option
3. Select which chaincode on the channels is exposed, as well as which are the endorsering peers for the chaincode by selecting both Example02 and Marbles for the channel boaventuraorderer, and then assign peer0.boaventura.com and peer1.boaventura.com for each sample as indicated by the picture below, then click on Submit button:
4. Now, you have to restart your gateway so that your changes can take place. Select your gateway row as done earlier and then click on this button to restart it
Now that your chaincode was exposed through the REST Gateway, it is our time to get started by invoking the samples APIs. You can use curl, Postman or whatever tool that can perform http requests in order to call the rest APIs. I decided to implement everything in Postman since it is a fast and agile tool for doing this sort of REST API calls. So, let ‘s get our hands dirty with the OBCS REST APIs. However, it is important to have an overview before start calling the APIs. The following are the REST APIs you will be playing with in this lab:
• getVersion: used to check your connectivity to the gateway
http://<gatewayhostname>:<gatewayport>/bcsgw/rest/version
• Query: used for querying information returned by chaincode functions
http://<gatewayhostname>:<gatewayport>/bcsgw/rest/v1/transaction/query
• Invocation: used to invoke functions implemented in your chaincode
http://<gatewayhostname>:<gatewayport>/bcsgw/rest/v1/transaction/invocation
• AsyncInvocation: Use this operation to invoke those functions in asynchronous mode
http://<gatewayhostname>:<gatewayport>/bcsgw/rest/v1/transaction/asyncInvocation
• GetStatus (of an async transaction)
http://<gatewayhostname>:<gatewayport>/bcsgw/rest/v1/transaction?channel=<name>&txid=<id>
• WaitStatus (return a list of transactions)
http://<gatewayhostname>:<gatewayport>/bcsgw/rest/v1/transaction/waitStatus
In order to make things easier, I have created two files that you can import into your Postman environment: OBCS Workshop.postman_environment.json and Oracle Blockchain Cloud Services workshop.postman_collection.json. They have all sample APIs for both Example02 and Marble implemented as REST calls within a postman collection, and they can be found here. That said, you will be able to identify all the REST APIs mentioned above while calling the samples in Postman.
As such, let’s do the following to get started calling the APIs:
5. Open Postman in your environment
6. Prior to send your first request, don’t forget to change the hostname and port to point to your <yourOBCSHostIP>:<yourOBCSHostPort> by changing your Postman environment configuration as shown in the picture below:
7. Now, to illustrate an example of a call for /bcsgw/rest/v1/transaction/query, you can call whatever API that returns a response. For this example, I will use the Query A and Query B from the Example02 sample. This is the payload that must be sent in order to call a chaincode function(implemented in GO Language) through a POST REST API call to the query endpoint.
Essentially you must provide the following to the request body:
· channel: boaventuraorderer
· chaincode: obcs-example02
· chaincode version: v0,
· method(the function implemented in GO Lang): invoke
· arguments passed to the function.
8. Now let’s call the Query A operation by clicking the blue send Button in Postman. You should receive a response with a result containing the value stored in “A”.
Alternatively, you could call the same operation by using curl
curl -X POST \
http://<yourOBCSHostIP>:<yourOBCSHostPort>/bcsgw/rest/v1/transaction/query \
-H ‘cache-control: no-cache’ \
-H ‘content-type: application/json’ \
-H ‘postman-token: 6416bfb1-ea1e-0e97-ddc8–71a0fd5b7605’ \
-d ‘{
“channel”: “boaventuraorderer”,
“chaincode”: “obcs-example02”,
“chaincodeVer”: “v0”,
“method”:”invoke”,
“args”:[“query”,”a”]
}’
9. Repeat the same step for Query B and see what you get.
Again, you could be calling the same operation by using curl as done earlier
curl -X POST \
http://<yourOBCSHostIP>:<yourOBCSHostPort>/bcsgw/rest/v1/transaction/query \
-H ‘cache-control: no-cache’ \
-H ‘content-type: application/json’ \
-H ‘postman-token: 6416bfb1-ea1e-0e97-ddc8–71a0fd5b7605’ \
-d ‘{
“channel”: “boaventuraorderer”,
“chaincode”: “obcs-example02”,
“chaincodeVer”: “v0”,
“method”:”invoke”,
“args”:[“query”,”a”]
}’
Note that in both cases you are calling a query endpoint /bcsgw/rest/v1/transaction/query, as highlighted in red on both pictures above. Also, a result is returned with the current data currently stored in variables A and B.
10. Now, let’s give a try in another function(Transfer from A to B). Go to the Postman collection and open a new tab and then click on the send button.
Again, you could be calling the same operation by using curl as done earlier
curl -X POST \
http:// <yourOBCSHostIP>:<yourOBCSHostPort>/bcsgw/rest/v1/transaction/invocation \
-H ‘cache-control: no-cache’ \
-H ‘content-type: application/json’ \
-H ‘postman-token: 70006ff2–2faa-f9c9–05a3–3437ddd4c773’ \
-d ‘{
“channel”: “boaventuraorderer”,
“chaincode”: “obcs-example02”,
“chaincodeVer”: “v0”,
“method”:”invoke”,
“args”:[“move”,”a”,”b”,200]
}’
Note that in this example, you have moved 200 from A to B by calling this endpoint /bcsgw/rest/v1/transaction/invocation. Since this was a transaction, that did not return any result data, then I had to call the invocation endpoint, as opposed to what I did in the previous step, where I called the query endpoint. Additionally, note that the response has transactionID and does not have a result field.
Also, as we have done in the previous lab, you can find information about any transactions in the ledger by going to the Channel tab under the ledger pane. You should be able to find your latest call over there.
11. Now execute Query A and Query B to make sure that data has really changed as expected.
Note that values has changed from 700 to 500 for A and -300 to -100 for B since you called the function to move value from variables. This confirms our lab has worked as expected, and thus now it is your turn to explore and give a try yourself on the other APIs that have been provided within the Postman collection. Enjoy it!!
Please clap on this article if it has helped you to understand a bit about Oracle Autonomous Blockchain Cloud Service and how to use their REST APIs and the REST Proxy. And please leave a comment and state your feedback. This is very important to help me keep writing new articles about this sort of content.
