Using OpenRPC Mock Server to test against an Ethereum JSON-RPC API

Stevan Lohja
Jun 11, 2019 · 4 min read
Image for post
Image for post
OpenRPC

The open-rpc-mock-server allows developers to run and test against their APIs in a local and lightweight environment.

Environment requirements

Create a new project

Image for post
Image for post
  • Create a project directory and initialize a new project.
mkdir MockServerDemo && cd MockServerDemo && npm init
  • Create an openrpc.json file. This is a document (or set of documents) that defines or describes an API. An OpenRPC definition uses and conforms to the OpenRPC Specification.
touch openrpc.json
  • Install the open-rpc-mock-server to your local project.
npm install --save @open-rpc/mock-server

At this point, the project has an OpenRPC API document (openrpc.json), and the Moch Server installed. However, the openrpc document is empty and final further configuration is needed to begin testing against the API.

Configure project

Image for post
Image for post

Configure package.json

  • Add a script to package.json to run the open-rpc-mock-server with ease.
"scripts": {
"mock-server": "open-rpc-mock-server"
},
  • Now, run mock-server
npm run mock-server

This will return an error (Unable to read openrpc.jsonfile...) because the openrpc.json document has no defined API. In fact, it is an empty file.

Define API in openrpc.json

The OpenRPC Playground is an online IDE for developers to write JSON-RPC based APIs and generates real-time documentation. However, developers can have these features in their VS Code IDE by installing the open-rpc extension.

Image for post
Image for post

Open openrpc.json in VS Code. To see real-time documentation preview in the IDE, access the command palette ⇧⌘P and search for the OpenRPC preview window provided by the open-rpc code extension.

For the purpose of this tutorial, we’ll copy the ethereum-json-rpc-specification created by ETC Labs Core. However, feel free to write custom APIs.

  • Copy the raw JSON code from the ethereum-json-rpc-specification and paste it into the working project’s openrpc.json. The OpenRPC preview window should now show real-time interactive documentation all inside VS Code!

With a complete openrpc.json document in the project, the mock-server can run successfully.

Run the Mock Server

Image for post
Image for post
  • Now that we have a complete openrpc document, run mock-server again.
npm run mock-server> mockserverdemo@1.0.0 mock-server <directory of openrpc.json document>
> open-rpc-mock-server

The mock-server will be running at http://localhost:3333/

Postman

Image for post
Image for post

With a mock-server running an ethereum-json-rpc API at localhost:3333, we can use Postman to begin running requests against the API.

If you’re not familiar with Postman, you can follow these steps:

  • Open Postman and create a New Collection and Add Request to the collection.
  • Request settings:
  • input http://localhost:3333 for URL
  • in the Headers tab, input Content-Type for Key and application/json for Value in the table.
  • in Body tab, select the raw radio button.

Send Request

OpenRPC allows developers to define example requests in their openrpc documents. These examples are also shown in the generated documentation.

Take a look at the web3_sha3 method in openrpc.json. Since we are not requesting real data from an actual blockchain, we can still test the requests with the examples provided in the API.

{
"name": "web3_sha3",
"summary": "Hashes data",
"description": "Hashes data using the Keccak-256 algorithm",
"params": [
{
"name": "data",
"description": "data to hash using the Keccak-256 algorithm",
"summary": "data to hash",
"schema": {
"type": "string",
"pattern": "^0x[a-fA-F\\d]+$"
}
}
],
"result": {
"name": "hashedData",
"description": "Keccak-256 hash of the given data",
"schema": {
"$ref": "#/components/schemas/Keccak"
}
},
"examples": [
{
"name": "sha3Example",
"params": [
{
"name": "sha3ParamExample",
"value": "0x68656c6c6f20776f726c64"
}
],
"result": {
"name": "sha3ResultExample",
"value": "0x47173285a8d7341e5e972fc677286384f802f8ef42a5ec5f03bbfa254cb01fad"
}
}
]
},

In Postman > Request > Body, input a raw JSON request against the web3_sha3 method.

{
"id": 1,
"jsonrpc": "2.0",
"method": "web3_sha3",
"params": [
"0x68656c6c6f20776f726c64"
]
}

Hint: Examples in the generated documentation have a copy-to-clipboard feature.

Then, click the SEND button which should return the example result:

{
"id": 1,
"jsonrpc": "2.0",
"result": "0x47173285a8d7341e5e972fc677286384f802f8ef42a5ec5f03bbfa254cb01fad"
}

Congratulations! You’ve successfully called a method from an Ethereum JSON-RPC API on a Mock-Server.


More OpenRPC

Visit https://open-rpc.org/ to learn more about the OpenRPC Project.


Interested in getting more involved with ETC? We’re focused on accelerating the development of Ethereum Classic and need your help! Reach out to us to see how you can get more involved today!

Our team links: About, Github, Medium, Twitter

Come chat with us on Discord

ETC Core

BLOG AS BEEN MOVED TO https://medium.com/etc-core/

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch

Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore

Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store