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

OpenRPC

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

Environment requirements

• at least node v10.15.0
• at least npm v6.4.1
• VS Code with the open-rpc code extension
• Postman

Create a new project

• 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

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.

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

• 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

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