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.
Create a new project
- Create a project directory and initialize a new project.
mkdir MockServerDemo && cd MockServerDemo && npm init
- Create an
openrpc.jsonfile. This is a document (or set of documents) that defines or describes an API. An OpenRPC definition uses and conforms to the OpenRPC Specification.
- 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.
- Add a script to
package.jsonto run the open-rpc-mock-server with ease.
- Now, run
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
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.
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
npm run mock-server
> firstname.lastname@example.org mock-server <directory of openrpc.json document>
The mock-server will be running at http://localhost:3333/
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:
- in the Headers tab, input
Content-Typefor Key and
application/jsonfor Value in the table.
- in Body tab, select the
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.
"summary": "Hashes data",
"description": "Hashes data using the Keccak-256 algorithm",
"description": "data to hash using the Keccak-256 algorithm",
"summary": "data to hash",
"description": "Keccak-256 hash of the given data",
In Postman > Request > Body, input a raw JSON request against the
Hint: Examples in the generated documentation have a copy-to-clipboard feature.
Then, click the SEND button which should return the example result:
Congratulations! You’ve successfully called a method from an Ethereum JSON-RPC API on a Mock-Server.
Visit https://open-rpc.org/ to learn more about the OpenRPC Project.