JSON-RPC与JSON-API的区别、优势对比及适用场景解析

Great question! Let’s dive into the differences between JSON-RPC and JSON-API, their unique strengths, and which one fits which scenario—no jargon overload, promise.

At their core, these two specs solve different problems, even though they both use JSON as their data format.

• Paradigm & Purpose
  JSON-RPC is a remote procedure call (RPC) protocol. Think of it like calling a function over the network: you send a request asking to execute a specific method with parameters, and you get back the result. It’s all about action, not data models.
  JSON-API is a RESTful resource-centric specification. It’s built around managing resources (like users, orders, or posts) and strictly follows HTTP’s built-in semantics (GET, POST, PATCH, DELETE). It’s designed for consistent, standardized CRUD operations and complex data relationships.

• Request/Response Structure
  JSON-RPC is minimal and flexible. A typical request looks like this:

  {"jsonrpc":"2.0","method":"getUser","params":[123],"id":1}
  

  And the response is equally straightforward:

  {"jsonrpc":"2.0","result":{"id":123,"name":"Alice"},"id":1}
  

  JSON-API enforces a strict structure focused on resources. A GET request for a user might return:

  {
    "data": {
      "type": "users",
      "id": "123",
      "attributes": {
        "name": "Alice Smith",
        "email": "alice@example.com"
      },
      "relationships": {
        "orders": {
          "links": {"related": "/users/123/orders"}
        }
      }
    }
  }
  

• HTTP Integration
  JSON-RPC doesn’t care about HTTP methods—you almost always use POST for every request, and HTTP status codes are often ignored (errors are handled in the JSON response).
  JSON-API leans hard into HTTP: you use GET to fetch resources, POST to create, PATCH to update, DELETE to remove. It relies on standard HTTP status codes (200 for success, 404 for not found, etc.) and features like caching.

• Simplicity & Speed
  No complex resource rules to follow. If you just need to trigger a specific action (like processOrder(456) or calculateTax(100)), JSON-RPC gets out of your way. It’s perfect for quick, small-scale integrations.
• Flexible Batch Calls
  You can send multiple method requests in a single payload, which reduces round-trips between client and server. Great for internal services that need to run several operations at once.
• Lightweight Payloads
  No extra metadata (like type or attributes) cluttering up your JSON. This makes it ideal for low-bandwidth environments or scenarios where every byte counts.

• Standardized Resource Management
  Everyone on your team (or third-party developers) knows exactly how to structure requests and responses. No more debating whether to use /user/123 or /getUser?id=123—the spec defines it all. This is a game-changer for large teams or public APIs.
• Built-in Best Practices
  JSON-API includes out-of-the-box support for pagination, filtering, sorting, and relationship fetching. You don’t have to reinvent these features; the spec tells you how to implement them.
• Self-Documenting & Tooling-Friendly
  Because the structure is standardized, tools can auto-generate API docs, client libraries, and even validation logic. New developers can jump in quickly without digging through custom code.

When to Pick JSON-RPC #

• Internal service-to-service communication (e.g., a payment service calling a tax calculation service)
• Simple, action-focused operations that aren’t CRUD (like triggering a password reset or running a report)
• Low-bandwidth environments or mobile apps where payload size matters
• Small projects or prototypes where you want to avoid over-engineering

When to Pick JSON-API #

• Building public RESTful APIs that third-party developers will integrate with
• Complex applications with interconnected resources (e.g., e-commerce platforms with users, orders, and products)
• Projects where you want to leverage HTTP caching, status codes, and other web standards
• Large teams that need a consistent API design to reduce miscommunication

内容的提问来源于stack exchange，提问作者Dmitry Bubnenkov