The idea of web services or online APIs isn’t new. There is a dedicated style of the software architecture which focuses on methodologies, communication protocols and structures of the applications which are built around the concept of web services. It is called service-oriented architecture (SOA) and is also applied in the field of software design.

Many different protocols and methodologies have been developed for composing web services and providing descriptions for them. This article is not intended to classify them, but for simplicity we can divide the specifications into two groups: RPC family and REST APIs.

The software developed in our company doesn’t differ from the others in the matter of web service utilization. Our systems are integrated to dozens of APIs and provide web-services for even more other applications. The main protocol used for web services is JSON-RPC 2.0.

JSON-RPC is of course not the only RPC protocol, but it is known for its simplicity and brief specification. As it can be implied from its name, the protocol uses JSON as the data serialization format. JSON is widely used and is considered to be more concise compared to other human readable serialization formats like XML. Although XML is a mature technology and supports extension natively (which can be “guessed” from its name), JSON got popularity along with wide adaptation of JavaScript. JSON is also used in the majority of REST API as well.

JSON-RPC powers the language server protocol (LSP). Many programming languages implement it for integration with text editors and IDEs in order to provide better experience during application development.

The few notable features of the protocol are being transport agnostic (can be used with raw TCP/UDP connections and is great with web sockets), support of notifications (client's lack of interest in the corresponding Response object) and batch request processing functionality.

{
  "jsonrpc": "2.0",
  "method": "subtract",
  "params": [
    42,
    23
  ],
  "id": 1
}

Fig. 1. JSON-RPC2.0 request example

Fig. 3. Basic OpenRPC definition

A service description may include generic information about a web-service including its version and license, the URL path of the service and definition of its methods.

A method definition by an OpenRPC specification includes it's name, summary and the structure of both request and response objects. It may also provide properties for indicating whether a certain method is deprecated or not and how the method is going to receive it's arguments (positional and named arguments). The request and response objects are defined using JSON schema.

{
  "methods": [
    {
      "name": "start_transaction",
      "summary": "Start signing transaction",
      "tags": [
        {
          "name": "t"
        }
      ],
      "params": [
        {
          "name": "title",
          "required": true,
          "schema": {
            "type": "object"
          },
          "deprecated": false
        },
        {
          "name": "callback",
          "required": true,
          "schema": {
            "type": "string"
          },
          "deprecated": false
        },
        {
          "name": "file",
          "required": true,
          "schema": {
            "type": "object"
          },
          "deprecated": false
        },
        {
          "name": "signers",
          "required": true,
          "schema": {
            "type": "array"
          },
          "deprecated": false
        }
      ],
      "result": {},
      "deprecated": false,
      "paramStructure": "by-name"
    }
  ]
}

Fig. 4. A JSON-RPC method definition using OpenRPC specification

Fig.4 presents a description of start_transaction method with four arguments: title, callback, file, signers. It also indicated that the method isn't deprecated ("deprecated": false) and that the arguments must be passed by name ("paramStructure": "by-name"). The result key must contain the structure of the JSON-RPC 2.0 result object.

The definition of all methods provided by a single service is generated from our code automatically. As our code base is in Python we can use the dynamic nature of the language and existing type annotations for composing the OpenRPC document. A (very) simplified and (very) limited implementation of a method definition generation may look like this:

from enum import StrEnum
from typing import Callable


def openrpc_spec(
    functions: list[Callable],
    title: str,
    version: str,
    server: str
) -> dict:
    # mapping between Python's built-in types and JSON types
    typedef: dict = {
        int: "number",
        float: "number",
        str: "string",
        bool: "boolean",
        list: "array",
        tuple: "array",
        dict: "object",
    }

    methods: list = []
    for func in functions:
        summary: str = func.__doc__ or ''
        params: list = []

        for param, typ in func.__annotations__.items():
            # skip the result definition
            if param == 'return':
                continue

            if jtype := typedef.get(typ):
                schema = {"type": jtype}
            elif issubclass(typ, StrEnum):
                schema = {"type": "string", "enum": tuple(typ)}
            else:
                schema = {"type": str(typ)}

            # generate the definition for the method
            params.append({
                "name": param,
                "required": True,
                "schema": schema,
                "deprecated": False,
            })

        methods.append({
            "name": func.__name__,
            "summary": summary and summary.strip(),
            "tags": [{"name": "t"}],
            "params": params,
            "result": '{}',
            "deprecated": False,
            "errors": [],
            "paramStructure": "by-name",  # by-position | either
        })

    return {
        "openrpc": "1.3.1",
        "info": {
            "title": title,
            "version": version,
            "license": {"name": ""},
        },
        "servers": [{"url": server}],
        "methods": methods,
    }


def square(number: int) -> None:
    ...


def append(value: str, collection: list, unique: bool) -> list:
    ...


print(
    openrpc_spec(
        [square, append],
        'My JSON-RPC 2.0 service',
        '0.0.1',
        '/json-rpc'
    )
)

Fig. 5. OpenRPC method definition generation in Python

The code in fig.5 tries to map built-in Python data types to JSON schema defined types and also tries to detect some types like StrEnum. It is simplified for the article and obviously lacks the response object structure generation and nested object definition, but it's a step in the right direction and may work for simple services. We run a slightly modified and complete version of this code for generating openrpc.json files.

Being able to easily provide and consume a web service or an API is an essential part of the modern IT infrastructure. In the world of complex standards and protocols it's always a nice thing to have a simpler approach for solving a problem. For our company that simpler approach for web service development was choosing JSON-RPC 2.0 as our main protocol. Spicing it with OpenRPC specification we are able to provide web services to hundreds of our clients who can easily integrate to the system we are developing.

Of course there isn't a silver bullet for solving all issues or a unified technology for all aspects of life. Thus everyone must find their own niche toolbox.