One of the mechanisms supporting SUSANOO’s transparent proxy is dynamic dispatch.
Suppose a device-control class has these methods:
device.move(...)
device.stop()
device.get_position()
A conventional Web API would define corresponding server-side endpoints such as /move, /stop, and /get_position individually. With dynamic dispatch, the client instead sends the method name and arguments to the server. The server finds and invokes the matching method on the device class.
client.move(...)
↓
network
↓
server
↓
device.move(...)
For example, when a control class gains a method:
def measure(self, time):
...
The client can call device.measure(10) across the network without adding a dedicated measure handler to the communication layer.
The basic principle in SUSANOO is to implement device control as an ordinary Python class first, then expose its functionality through a communication layer. This minimizes changes to communication code when devices or methods are added. It is useful in research environments, where instrument APIs differ substantially and frequently evolve.
However, dynamic dispatch alone makes the interface difficult to discover externally. Users may not know which methods exist, their parameters, whether an argument is an int or float, or their return types. SUSANOO therefore also provides a way to define an explicit API interface.
FastAPI can use Pydantic to specify the types and structure of API inputs:
class MoveRequest(BaseModel):
x: float
y: float
z: float
This declares that x, y, and z are floating-point values. Pydantic is not merely documentation: it also validates whether required fields are present and whether the supplied types and structures are valid.
FastAPI can generate an OpenAPI specification from such API definitions. OpenAPI describes the available endpoints, HTTP methods, input arguments, and returned data in a machine-readable form.
Python control class
↓
Pydantic type/interface definitions
↓
FastAPI
↓
OpenAPI
OpenAPI allows people to inspect an API and compatible tools or client programs to obtain its structure programmatically.
SUSANOO can use either approach according to the application.
Methods on the control class can be exposed over the network with little additional definition:
device class
↓
dynamic dispatch
↓
network API
Adding device-specific methods requires minimal changes to the communication layer. This approach is suited to new instruments, experimental control, rapidly changing APIs, and small device servers.
When the public API should be defined in advance, its interface can be specified with Pydantic:
device class
↓
explicit API definition
↓
Pydantic
↓
FastAPI
↓
OpenAPI
This makes API names, arguments, types, return values, and data structures explicit. It is useful for common interfaces across robots, stable externally published APIs, documentation, and OpenAPI-compatible tooling.
These approaches are not mutually exclusive. SUSANOO can retain dynamic exposure of control classes while explicitly defining interfaces with Pydantic/OpenAPI where needed.
Requiring a strict API definition for every device increases the work needed to add instruments. Conversely, making everything dynamic makes interfaces harder for external users to understand. The intended distinction is:
Parts requiring flexibility
→ dynamic dispatch
Parts requiring a fixed specification
→ Pydantic / OpenAPI
Relationship to BL774 (historical note)
The BL774 REST API also exposes device functionality relatively dynamically, an approach conceptually close to SUSANOO’s dynamic dispatch. There have also been attempts to describe BL774 APIs using OpenAPI (the information in the original note may be outdated).
The original author considered that, at the time, BL774 did not yet actively use per-device Pydantic-style typed interface definitions as OpenAPI specifications. SUSANOO retained ideas compatible with BL774 while allowing more explicit Pydantic/OpenAPI definitions for devices that need them.
This is a translation of an archived Japanese design note. Statements about BL774 reflect the original note and have not been independently updated.