JSON-RPC

JSON 포맷을 사용하는 원격 프로시저 호출(RPC) 프로토콜이다. 클라이언트가# 서버의 메서드를 마치 로컬 함수처럼 호출할 수 있게 해주는 경량 통신 규약이다.

핵심 특징: Transport-independent (전송 계층 독립적) - HTTP, TCP, WebSocket 등 어떤 전송 프로토콜 위에서도 동작 가능하다.

해당 개념이 필요한 이유

• 원격 함수 호출 표준화: 서로 다른 시스템 간 함수 호출을 일관된 방식으로 처리
• 경량 프로토콜: XML-RPC에 비해 간결한 JSON 포맷으로 오버헤드 감소
• 비동기 처리 지원: 여러 요청을 동시에 보내고 비동기로 응답 받기 가능
• 알림 기능: 응답이 필요 없는 일방향 통신 지원 (Notification)

AS-IS

전통적인 REST API는 리소스 중심이며, 각 동작마다 URL 엔드포인트가 필요하다.

// REST API 방식: 엔드포인트마다 별도 URL
POST /api/users/create
POST /api/users/update
POST /api/users/delete
GET  /api/users/list
GET  /api/products/calculate-price

문제점:

• URL 관리 복잡도 증가
• 함수 호출 의미가 URL에 분산됨
• 메서드 이름과 URL 매핑 불일치 가능

TO-BE

JSON-RPC는 단일 엔드포인트에서 메서드 이름으로 함수를 호출한다.

// JSON-RPC 방식: 단일 엔드포인트에서 메서드 구분
POST /api/rpc
 
// 모든 호출이 동일한 구조
{"jsonrpc": "2.0", "method": "user.create", "params": {...}, "id": 1}
{"jsonrpc": "2.0", "method": "user.update", "params": {...}, "id": 2}
{"jsonrpc": "2.0", "method": "user.delete", "params": {...}, "id": 3}
{"jsonrpc": "2.0", "method": "product.calculatePrice", "params": {...}, "id": 4}

개선점:

• 단일 엔드포인트로 모든 함수 호출 처리
• 메서드 이름이 명시적으로 드러남
• 일관된 요청/응답 구조

JSON-RPC 메시지 3가지 타입

1. Request (요청)

클라이언트가 서버의 메서드를 호출할 때 사용한다.

{
  "jsonrpc": "2.0",
  "method": "subtract",
  "params": {"minuend": 42, "subtrahend": 23},
  "id": 3
}

필수 필드:

• method: 호출할 메서드 이름 (문자열)
• id: 요청-응답 매칭을 위한 식별자 (문자열 또는 정수)

선택 필드:

• params: 파라미터 (객체 또는 배열, 생략 가능)
• jsonrpc: 프로토콜 버전 (2.0에서 필수)

2. Response (응답)

서버가 요청에 대한 결과를 반환할 때 사용한다.

{
  "jsonrpc": "2.0",
  "result": 19,
  "id": 3
}

성공 시:

• result: 메서드 실행 결과
• id: 원래 요청의 id

실패 시:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid Request"
  },
  "id": null
}

• error: 오류 객체 (code, message 필수)
• id: 원래 요청의 id (파싱 실패 시 null)

3. Notification (알림)

응답이 필요 없는 일방향 메시지다. id 필드를 생략하면 서버는 응답하지 않는다.

{
  "jsonrpc": "2.0",
  "method": "update",
  "params": [1, 2, 3, 4, 5]
}

용도:

• 로그 전송
• 이벤트 알림
• 백그라운드 작업 트리거

JSON-RPC 통신 흐름

sequenceDiagram
    autonumber
    participant Client as Client
    participant Server as Server

    Note over Client,Server: 1. 일반 요청/응답
    Client->>Server: Request<br/>{"method": "add", "params": [2, 3], "id": 1}
    Server->>Server: add(2, 3) 실행
    Server->>Client: Response<br/>{"result": 5, "id": 1}

    Note over Client,Server: 2. 알림 (응답 없음)
    Client->>Server: Notification<br/>{"method": "log", "params": ["info"]}
    Note over Server: log 실행, 응답 없음

    Note over Client,Server: 3. 배치 요청 (비동기)
    Client->>Server: Batch Request<br/>[{"method": "sum", "id": 1},<br/>{"method": "multiply", "id": 2}]
    Server->>Server: 병렬 처리
    Server->>Client: Batch Response<br/>[{"result": 10, "id": 1},<br/>{"result": 20, "id": 2}]

핵심 흐름:

1. 클라이언트가 id와 함께 요청 전송
2. 서버가 메서드 실행 후 동일한 id로 응답 반환
3. 알림은 id 없이 전송되어 응답 없음
4. 배치 요청은 여러 호출을 배열로 묶어 전송 가능

버전별 주요 차이점

Version 1.0 (2005)

// Request
{"method": "echo", "params": ["Hello"], "id": 1}
 
// Response
{"result": "Hello", "error": null, "id": 1}

특징:

• error 필드가 항상 존재 (null 가능)
• jsonrpc 버전 필드 없음

Version 2.0 (2010, 현재 표준)

// Request
{"jsonrpc": "2.0", "method": "echo", "params": ["Hello"], "id": 1}
 
// Response (성공)
{"jsonrpc": "2.0", "result": "Hello", "id": 1}
 
// Response (실패)
{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid"}, "id": 1}

개선점:

• jsonrpc: "2.0" 필드로 버전 명시
• result와 error 중 하나만 존재 (배타적)
• Named parameters 지원 (params를 객체로 전달)
• 배치 요청 공식 지원

사전 정의된 오류 코드

Code	Message	의미
-32700	Parse error	JSON 파싱 실패
-32600	Invalid Request	요청 구조가 잘못됨
-32601	Method not found	메서드가 존재하지 않음
-32602	Invalid params	파라미터가 잘못됨
-32603	Internal error	서버 내부 오류

서버별 오류: -32000 ~ -32099 범위는 서버가 자유롭게 정의 가능

Transport-Independent 특성

JSON-RPC는 전송 계층에 독립적이다. 다양한 프로토콜 위에서 동작한다.

graph TB
    subgraph "JSON-RPC Protocol Layer"
        JSONRPC[JSON-RPC<br/>메시지 구조]
    end

    subgraph "Transport Layer (선택 가능)"
        HTTP[HTTP/HTTPS]
        WS[WebSocket]
        TCP[TCP Socket]
        IPC[IPC/Unix Socket]
    end

    JSONRPC --> HTTP
    JSONRPC --> WS
    JSONRPC --> TCP
    JSONRPC --> IPC

    HTTP --> Network[네트워크 전송]
    WS --> Network
    TCP --> Network
    IPC --> Local[로컬 프로세스]

예시:

• HTTP: 웹 API로 사용 (가장 일반적)
• WebSocket: 실시간 양방향 통신
• TCP: 고성능 마이크로서비스 간 통신
• IPC: 로컬 프로세스 간 통신

JSON-RPC vs REST API

특성	JSON-RPC	REST API
중심 개념	메서드(함수)	리소스
엔드포인트	단일 URL	리소스별 URL
HTTP 메서드	주로 POST	GET, POST, PUT, DELETE
캐싱	어려움	HTTP 캐싱 활용 가능
배치 요청	기본 지원	비표준
알림	기본 지원	없음

JSON-RPC를 선택하는 경우:

• RPC 스타일의 API가 자연스러운 경우
• 배치 요청이 필요한 경우
• 내부 마이크로서비스 통신
• LSP 같은 프로토콜 계층이 필요한 경우

참고 문서

• JSON-RPC 2.0 Specification
• JSON-RPC - Wikipedia