Using OpenRPC Mock Server to test against an Ethereum JSON-RPC API
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.json
file...) 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 andapplication/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.