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.
|Feature||JSON-RPC 1.0||JSON-RPC 2.0|
|Version Specification||Optional version number||Mandatory "2.0" in jsonrpc field of the request|
|Error Format||Simple strings returned as errors||Error object with error code and message|
|Data Format||Supported XML and others||Standardized JSON as the official data format|
|Batch Call||No specification for batch calls||Batch calls with arrays allowed for efficiency|
|Notification Method||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.
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||Description||Corresponding HTTP Status Code|
|-32600||Invalid Request||400 Bad Request|
|-32601||Method not found||404 Not Found|
|-32602||Invalid params||400 Bad Request|
|-32603||Internal error||500 Internal Server Error|
|-32000 to -32099||Server error||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!