Calling a REST API from Transaction Processor Functions
The status of this feature is experimental. We welcome your feedback on the utility of this feature. We may evolve the feature in the future to make it more generally useful. While we will strive to ensure backwards compatibility this cannot be guaranteed.
In some cases it is desirable to be able to call REST APIs from transaction processor functions. This allows you to move complex computation off the blockchain. Calling the REST API allows the transaction processor function to off-board complex or expensive computation to a centrally or peer hosted service.
Calling an External REST Service
post(url,data) function is available to transaction processor functions, allowing them to pass a concept, transaction, asset or participant to an external service. The data is serialized to JSON and the data is sent to the url using an HTTP POST using the
application/json content encoding.
post function is supported in all runtime environments: web (playground), Node.js (embedded) and Hyperledger Fabric v1.0.
post method returns a
Promise to a JS Object that contains the results returned by the remote server. The JS Object has the following properties:
- statusCode : the HTTP statusCode
- body : the HTTP response body
Note that HTTP response codes from 200 to 300 are returned as a resolved Promise, while any other response codes cause the Promise to be rejected. Rejected promises may be handled using a
.catch Promise handler.
body property of the response is automatically converted to a JS Object if possible, otherwise it is returned as a
Transaction processor functions may optionally call the
getSerializer().fromJSON(object) function to convert a reponse body JS Object back into a Composer asset/participant/transaction.
Idempotency and Consensus
The result of the REST request should be a pure function (idempotent) to ensure that all peers get the same results with the same inputs. If this restriction is honored then the risk of consensus failure is minimized.
Each peer will make a call to the REST service.
HTTP requests from the web browser will need to be CORS compliant. This requires the server be setup to receive the OPTIONS method and return appropriate headers.
Docker Network Resolution
HTTP request from the HLF chaincode container require DNS resolution and network are in place. For example, with the default Docker container one cannot use http://localhost as this does not resolve to the host machine inside the Docker container. The easiest workaround is to use a DNS name that is publicly resolvable.