Protocol Design

pyRPC uses JSON-RPC 2.0 over HTTP POST. One endpoint, one format, no surprises.

Request

POST /rpc
Content-Type: application/json

{
  "id": "unique-request-id",
  "method": "add",
  "params": { "a": 10, "b": 5 }
}

• id — Unique identifier for the request (UUID or string)
• method — Procedure name
• params — Object (named) or array (positional) of arguments

Response

Success:

{
  "id": "unique-request-id",
  "result": 15
}

Error:

{
  "id": "unique-request-id",
  "error": {
    "code": -32602,
    "message": "Invalid params"
  }
}

Introspection

One of pyRPC's most powerful features is built-in introspection. By default, your RPC endpoint also responds to GET requests:

GET /rpc

The server returns a full JSON schema of every registered procedure, including:

• Parameter names and types
• Return types
• Docstrings
• Namespaces

This is the "Source of Truth" that pyrpc codegen uses to synchronize your TypeScript contracts.

Why JSON-RPC?

• Zero Ambiguity — Unlike REST, where status codes (200, 201, 204) and methods (PUT vs PATCH) are often debated, JSON-RPC has one way to succeed and one way to fail.
• Easy Debugging — Requests are plain JSON objects. You can copy-paste them from your browser's network tab directly into a test script.
• Batched Requests — The protocol natively supports sending multiple calls in a single HTTP request (coming soon to pyRPC).

Next

• Error Handling — Error codes and propagation
• Server — Mounting, procedures, context