Introduction
When developers think about APIs, REST is usually the first architecture that comes to mind. REST APIs power countless applications, from mobile apps and web platforms to cloud services. They are flexible, widely adopted, and supported by nearly every programming language and framework.
However, REST is not always the best choice, especially for internal services communicating within an organization. In many cases, teams need a simpler and more efficient way for services to interact. This is where JSON-RPC becomes an attractive alternative.
JSON-RPC is a lightweight remote procedure call (RPC) protocol that uses JSON for data exchange. Instead of designing multiple endpoints around resources, JSON-RPC allows applications to directly call methods on a remote service.
In this article, we'll explore what JSON-RPC is, how it differs from REST, how to build internal APIs using JSON-RPC, and when it makes sense to use it.
What Is JSON-RPC?
JSON-RPC is a simple protocol that enables one application to call functions or methods on another application over a network.
Unlike REST, which revolves around resources and HTTP verbs such as GET, POST, PUT, and DELETE, JSON-RPC focuses on executing methods.
A JSON-RPC request contains:
JSON-RPC version
Method name
Parameters
Request ID
Example request:
{
"jsonrpc": "2.0",
"method": "GetEmployee",
"params": {
"employeeId": 101
},
"id": 1
}
Example response:
{
"jsonrpc": "2.0",
"result": {
"employeeId": 101,
"name": "John Smith",
"department": "Engineering"
},
"id": 1
}
The client simply calls a method and receives a result.
Why Use JSON-RPC for Internal APIs?
Many organizations build dozens or even hundreds of internal services. Managing numerous REST endpoints can become complex over time.
JSON-RPC offers several advantages for internal systems.
Simpler API Design
Instead of creating multiple routes and resource structures, developers expose methods directly.
For example:
REST approach:
GET /employees/101
POST /employees
PUT /employees/101
DELETE /employees/101
JSON-RPC approach:
GetEmployee()
CreateEmployee()
UpdateEmployee()
DeleteEmployee()
The API becomes more aligned with business operations.
Reduced Network Overhead
JSON-RPC requests are typically smaller because they do not require extensive URL structures or multiple endpoint definitions.
This can improve communication efficiency between microservices.
Easier Internal Service Communication
Internal systems often need direct function calls rather than resource-based interactions.
JSON-RPC naturally supports this model.
Consistent Communication Pattern
Most requests follow the same structure regardless of the operation being performed.
This consistency simplifies implementation.
REST vs JSON-RPC
Let's compare the two approaches.
| Feature | REST | JSON-RPC |
|---|
| Architecture Style | Resource-based | Method-based |
| Endpoints | Multiple endpoints | Usually single endpoint |
| HTTP Verbs | GET, POST, PUT, DELETE | Typically POST |
| Learning Curve | Moderate | Simple |
| Internal Services | Good | Excellent |
| Public APIs | Excellent | Less common |
| Payload Structure | Varies | Consistent |
REST remains ideal for public-facing APIs, while JSON-RPC is often a strong choice for internal service communication.
How JSON-RPC Works
The communication flow is straightforward.
Client sends a JSON request.
Server identifies the requested method.
Method executes.
Result is returned as JSON.
Example workflow:
Client
|
v
JSON-RPC Request
|
v
Server Method
|
v
JSON-RPC Response
Because every request follows a standard structure, implementation becomes predictable and easier to maintain.
Building a Simple JSON-RPC API
Let's create a basic employee service.
Step 1: Client Request
{
"jsonrpc": "2.0",
"method": "GetEmployee",
"params": {
"id": 101
},
"id": 1001
}
Step 2: Server Processing
Pseudo-code:
public Employee GetEmployee(int id)
{
return employeeRepository.Find(id);
}
Step 3: Response
{
"jsonrpc": "2.0",
"result": {
"id": 101,
"name": "John Smith"
},
"id": 1001
}
The client receives the requested data without needing multiple routes or endpoint definitions.
Practical Use Cases for JSON-RPC
JSON-RPC is particularly useful in several scenarios.
Microservices Communication
Large applications often consist of multiple services communicating internally.
Examples:
User Service
Payment Service
Notification Service
Inventory Service
JSON-RPC enables direct method calls between these services.
Internal Business Platforms
Organizations frequently develop:
HR systems
Finance platforms
ERP solutions
Customer support systems
JSON-RPC can simplify communication among these components.
Real-Time Systems
Applications that require frequent requests can benefit from JSON-RPC's lightweight structure.
Examples include:
Trading platforms
Monitoring systems
IoT applications
Backend-to-Backend Communication
Internal backend services often need operation-based communication rather than resource-based APIs.
JSON-RPC aligns naturally with this requirement.
Error Handling in JSON-RPC
JSON-RPC provides a standardized error format.
Example:
{
"jsonrpc": "2.0",
"error": {
"code": -32601,
"message": "Method not found"
},
"id": 1
}
This makes debugging easier because every error follows a predictable structure.
Common errors include:
Invalid request
Method not found
Invalid parameters
Internal server error
Best Practices
When building internal APIs with JSON-RPC, follow these recommendations.
Use Clear Method Names
Choose descriptive method names that represent business actions.
Examples:
CreateOrder
ProcessPayment
GetEmployee
GenerateReport
Avoid vague names such as:
Execute
Run
Process
Implement Authentication
Even internal services should use proper authentication and authorization mechanisms.
Popular options include:
JWT tokens
API keys
OAuth
Service accounts
Validate Input Parameters
Always validate incoming data before processing requests.
This improves security and system stability.
Standardize Error Responses
Ensure all services return errors using a consistent structure.
This simplifies troubleshooting.
Add Logging and Monitoring
Track:
Request volume
Response times
Failures
Method usage
Monitoring helps identify performance and reliability issues.
When Should You Choose JSON-RPC?
JSON-RPC is a good choice when:
APIs are used primarily inside an organization.
Services need direct operation-based communication.
Simplicity and performance are priorities.
Multiple microservices interact frequently.
Resource-based REST design adds unnecessary complexity.
REST remains a better option when exposing APIs to external developers or third-party integrations.
Conclusion
JSON-RPC offers a simple and efficient alternative to REST for internal API development. By focusing on method calls rather than resources, it reduces complexity and creates a communication model that closely resembles local function execution.
For organizations building microservices, internal business platforms, or backend service architectures, JSON-RPC can simplify development while improving consistency and performance. Although REST continues to dominate public API ecosystems, JSON-RPC remains a valuable tool for teams looking to streamline internal service communication and reduce architectural overhead.
Henry EdwardPosted Jul 9, 2026, 1:40 PM
Nice comparison. I think JSON-RPC is often overlooked because REST is the default choice for almost everything. For internal services where both sides are controlled by the same team, calling methods directly can make the API much simpler. I still prefer REST for public APIs, but for backend-to-backend communication, JSON-RPC can be a really clean solution.