Corda 5’s New HTTP RPC API for Node Interaction

One common piece of feedback we got from CorDapp developers was about the RPC API used to communicate with the Corda node. They asked: why don’t we use the HTTP API to ease things and allow developers to communicate with the Corda node with a simple HTTP client rather than having to build a client layer? We took that valuable feedback and applied it to our development strategy, and with Corda 5, you get what you asked for. We are introducing the new HTTP RPC API for node interaction.

The Problem with Artemis RPC

Corda 4 offered node interaction via the RPC layer using Artemis RPC, allowing node operators to trigger specific actions on the node and obtain helpful information about node internals. The main disadvantage of this approach is that Artemis RPC is very JVM-centric, which makes RPC calls from non-JVM platforms very difficult. 

It leads to an overhead of developing an extra client module and running another Java process specifically for node interaction. Thus with Corda 5, we are reconsidering this approach and switching from Artemis RPC to HTTP RPC.

Corda 5 HTTP RPC Layer

HTTP RPC is a separate subsystem within the Corda node. It starts a web server that is responsible for HTTP GET and HTTP POST requests from HTTP Clients. 

As the node starts up, it looks for the HTTP RPC enabled service and dynamically builds a list of endpoints that are exposed by the webserver for users to interact with the node. Support for OpenAPI has been added; thus, the endpoints conform to the OpenAPI standards. To make things easier as the node runs, it also hosts Swagger UI, allowing users to invoke HTTP RPC methods easily.

For security purposes, SSL/HTTPs has been made mandatory for production mode as well as in dev mode; however, plain HTTP can be used.

More notable features include support for single sign-on (SSO) and a new durable stream feature.

Flow Changes for HTTP RPC

There have been some notable changes to the flows in Corda 5. For the purposes of this article, we will talk about the changes from the perspective of flow invocation using HTTP RPC.

Below is a sample flow code snippet that was written for Corda 5. Let’s take a close look:

• The first thing to notice is the implementation of the Flow interface; flow logic is gone.
• We still need the StartableByRPC annotation; nothing changes there.
• We have introduced a new data classRpcStartFlowRequestParameters, used to receive the parameters passed to the flow. It contains a single field of type ‘String’, which is used for the parameters passed as a JSON string.

• The flow must have a single parameter constructor which accepts RpcStartFlowRequestParameters as a parameter, and it should also be annotated with JsonConstructor.
• The marshaling of the JSON is handled by the JsonMarshallingService which is a Corda Service, which can be injected into the flow in Corda 5 using the CordaInject annotation.

Starting Flow with HTTP RPC

Flows can be started using the HTTP POST endpoint. The endpoint accepts a parameter of the RPCFlowRequest instance, which contains the flowName, a clientId and the parameters JSON String.

Once the flow has started, the endpoint returns an instance of RpcFlowResponse as a response. It contains the flowId and the clientId.

The flowId can be used to query further information regarding the outcome of the flow using separate HTTP GET endpoints.

---

I believe that should get you excited about the new Dev Preview release of Corda 5 – no more building client modules, just build your CorDapps and interact with them with the new HTTP RPC layer. 

I hope you liked this post; thank you very much for reading.