Powered by JSON-RPC 2.0
Overview
It’s hard to imagine a modern software system which doesn’t either consume or
provide a means of
machine to machine communication. In fact most applications both provide and depend on various
web services, APIs etc.
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.
The power of JSON-RPC
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
The simplicity of the protocol allowed us to implement both client and
server libraries ourselves, thus not depending on third-party libraries.
Almost all software developed in VXSoft provide JSON-RPC based
web-services both for administrative purposes and for integrating with other
systems.
import uuid
import requests
requests.post(
'http://localhost/json-rpc',
json={
'jsonrpc': '2.0',
'method': 'subtract',
'params': [42, 23],
'id': str(uuid.uuid4())
}
)
Fig. 2. Simple JSON-RPC2.0 request using Python's "requests" library
One of the disadvantages of the JSON-RPC 2.0 specification is the
lack of rules for describing a service like
WSDL for
SOAP. Another limitation of
the protocol is missing
security standards.
To solve the problem with a service description, after some research we
stumbled upon OpenRPC specification. It
is specifically designed for describing and documenting
JSON-RPC 2.0 based web service and is using
JSON schema for defining
requests and responses. By utilizing the OpenRPC we can generate
machine readable structures of our services and then automatically use them
in client libraries for composing requests and validating responses. The
description of a service documented using OpenRPC specification can
be discovered by the
/openrpc.json path of the URL.
{
"openrpc": "1.3.1",
"info": {
"title": "My JSONRPC2.0 service",
"version": "0.0.1",
"license": {
"name": ""
}
},
"servers": [
{
"url": "/json-rpc"
}
],
"methods": [
]
}
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.
Conclusion
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.
Powered by JSON-RPC 2.0
![Powered by JSON-RPC 2.0]()
Reviewed by Vladimir Poghosyan
on
14:09
Rating: 5
.png)
.png)
