Apidog

All-in-one Collaborative API Development Platform

API Design

API Documentation

API Designing

API Mock

API Automated Testing

Sign up for free

What is JSON-RPC(Remote Procedure Calls)?

Start for free
Contents
Home / Basic Knowledge / What is JSON-RPC(Remote Procedure Calls)?

What is JSON-RPC(Remote Procedure Calls)?

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.

JSON-RPC (JavaScript Object Notation Remote Procedure Call) offers a lightweight and straightforward protocol for seamless communication between software applications. Whether you're a web developer or working with distributed systems, JSON-RPC enables you to easily request services and invoke methods across different applications.

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 (JavaScript Object Notation Remote Procedure Call) is a lightweight remote procedure call (RPC) protocol that allows communication between different software applications over a network. It is based on the JSON data format, which is a lightweight data-interchange format that is easy for humans to read and write, as well as easy for machines to parse and generate.

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.

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 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.

img

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!

button