# JSON RPC

The `aiorpcx` module provides classes to interpret and construct JSON RPC protocol messages. Class instances are not used; all methods are class methods. Just call methods on the classes directly.

class `aiorpcx.``JSONRPC`

An abstract base class for concrete protocol classes. `JSONRPCv1` and `JSONRPCv2` are derived protocol classes implementing JSON RPC versions 1.0 and 2.0 in a strict way.

class `aiorpcx.``JSONRPCv1`

  A derived class of `JSONRPC` implementing version 1.0 of the specification.

class `aiorpcx.``JSONRPCv2`

  A derived class of `JSONRPC` implementing version 2.0 of the specification.

class `aiorpcx.``JSONRPCLoose`

  A derived class of `JSONRPC`. It accepts messages that conform to either version 1.0 or version 2.0. As it is loose, it will also accept messages that conform strictly to neither version.

  Unfortunately it is not possible to send messages that are acceptable to strict implementations of both versions 1.0 and 2.0, so it sends version 2.0 messages.

class `aiorpcx.``JSONRPCAutoDetect`

  Auto-detects the JSON RPC protocol version spoken by the remote side based on the first incoming message, from `JSONRPCv1`, `JSONRPCv2` and `JSONRPCLoose`. The RPC processor will then switch to that protocol version.

## Message interpretation

classmethod `JSONRPC.``message_to_item`(message)

  Convert a binary message into an RPC object describing the message and return it.

  Parameters

    message (bytes) – the message to interpret

  Returns

    the RPC object

  Return type

    `RPCRequest`, `RPCResponse` or `RPCBatch`.

  If the message is ill-formed, return an `RPCRequest` object with its `method` set to an `RPCError` instance describing the error.

## Message construction

These functions convert an RPC item into a binary message that can be passed over the network after framing.

classmethod `JSONRPC.``request_message`(item)

  Convert a request item to a message.

  Parameters

    item – an `RPCRequest` item

  Returns

    the message

  Return type

    bytes

classmethod `JSONRPC.``response_message`(item)

  Convert a response item to a message.

  Parameters

    item – an `RPCResponse` item

  Returns

    the message

  Return type

    bytes

classmethod `JSONRPC.``error_message`(item)

  Convert an error item to a message.

  Parameters

    item – an `RPCError` item

  Returns

    the message

  Return type

    bytes

classmethod `JSONRPC.``batch_message`(item)

  Convert a batch item to a message.

  Parameters

    item – an `RPCBatch` item

  Returns

    the message

  Return type

    bytes

classmethod `JSONRPC.``encode_payload`(payload)

  Encode a Python object as a JSON string and convert it to bytes. If the object cannot be encoded as JSON, a JSON “internal error” error message is returned instead, with ID equal to the “id” member of payload if that is a dictionary, otherwise `None`.

  Parameters

    payload – a Python object that can be represented as JSON. Numbers, strings, lists, dictionaries, `True`, `False` and `None` are all valid.

  Returns

    a JSON message

  Return type

    bytes