JSON-RPC is a remote procedure call protocol that uses JSON for encoding and is used by many users. So what if you need to send a request or something to test the JSON-RPC API? In this article, we will show you how to send a JSON-RPC API request and validate the response.
In this guide, we'll introduce the basics of JSON-RPC, explaining its structure and implementation. By the end, you'll be ready to enhance the interoperability and efficiency of your projects with JSON-RPC. Let's dive in!
What is the JSON-RPC?
JSON-RPC defines a simple and standardized way for one application to request services or invoke methods from another application using JSON messages over HTTP or other transport protocols. It is commonly used in web development and distributed systems to enable communication between different components or services.
Differences between JSON-RPC 1.0 and 2.0
Currently, JSON-RPC version 2.0 is the most widely used. So what's the difference between version 2.0 and 1.0? This section will like to introduce you to this point.
Optional version number
Mandatory "2.0" in jsonrpc field of the request
Simple strings returned as errors
Error object with error code and message
Supported XML and others
Standardized JSON as the official data format
No specification for batch calls
Batch calls with arrays allowed for efficiency
No notification-only methods
Added "notify" method for easier server notification
In this way, 2.0 unifies the JSON format, improves error handling, and expands functionality.
In a JSON-RPC request, the client sends a JSON object representing the method to be invoked, along with any required parameters. The server processes the request and sends back a JSON object containing the result of the method call or an error message if something went wrong.
The structure of a JSON-RPC request typically includes the following properties:
"jsonrpc": Specifies the version of the JSON-RPC protocol used (e.g., "2.0").
"method": Specifies the name of the method to be called.
"params": Contains the parameters to be passed to the method (optional).
"id": A unique identifier for the request, used to match the response to the corresponding request.
Methods and Status Codes in JSON-RPC
In JSON-RPC, similar to REST API, there are methods and status codes, but there are some differences from REST API.
JSON-RPC Methods First and foremost, JSON-RPC has two main methods for achieving Remote Procedure Calls:
rpc.call: Used for calling remote procedures and getting responses.
rpc.notify: A one-way call for notifications, which does not require a response.
rpc.call follows the request/response format for normal operations, allowing function calls and result returns. On the other hand, rpc.notify is a one-way notification method that does not expect a response.
Additionally, JSON-RPC 2.0 defines other methods such as:
rpc.discover: Retrieve a list of supported RPC methods.
rpc.status: Obtain status and metadata of the RPC server.
rpc.ping: Use ping/pong for liveliness confirmation.
rpc.cancel: Cancel delayed RPC calls, among others.
When using JSON-RPC, you can flexibly design your API by combining the basic rpc.call and rpc.notify methods with these auxiliary methods based on the context and requirements.
JSON-RPC Error Codes Like REST API, JSON-RPC also uses status codes to indicate the state of the request. However, unlike HTTP status codes like 200, 400, etc., JSON-RPC has its own exclusive error codes. In JSON-RPC, there is no specific status code like HTTP 200 OK when the response is successful; only error codes exist for error occurrences.
The correlation between JSON-RPC error codes and HTTP status codes is as follows:
JSON-RPC Error Code
Corresponding HTTP Status Code
400 Bad Request
Method not found
404 Not Found
400 Bad Request
500 Internal Server Error
-32000 to -32099
500 Internal Server Error
For JSON-RPC errors with codes starting from -32xxx, it is common to map them to appropriate HTTP status codes like 4xx or 5xx. Especially, -32600 and -32602 are input-related errors, so 400 Bad Request is suitable. -32601 indicates a method not found, hence 404 Not Found is appropriate. -32603 and -32xxx denote server-side errors, making 500 Internal Server Error appropriate.
Implementing the mapping of JSON-RPC error codes to HTTP status codes according to this table is crucial for proper functionality.
What is Apidog
Apidog is an integrated API collaboration platform that enables API documentation, API debugging, API mocking, and API automated testing. It is an advanced tool for API design, development, and testing. Apidog provides a comprehensive API management solution.
With Apidog, you can design, debug, test, and collaborate on your APIs on a unified platform, eliminating the need to switch between different tools and ensuring data consistency. One of the features of Apidog is its support for API debugging based on API definitions. With the presence of .proto files, Apidog can provide mocking functionality and also supports automatic request body generation.
Sending JSON-RPC API with Apidog
You can also use Apidog to send JSON-RPC APIs, and the transition from Postman to Apidog is almost seamless.
Apidog is a highly powerful API management tool that is also compatible with JSON-RPC. It provides comprehensive support for APIs using the HTTP protocol, as well as other protocols like GraphQL, WebSocket, and gRPC. Whatever type of API you want to design or test, Apidog is the tool to have.
Sending JSON-RPC requests with Apidog is a breeze. To send JSON-RPC API requests and validate responses or perform tests, simply select the JSON data format in the Body tab of the specific API in Apidog. It's incredibly convenient, so give it a try!