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