Skip to content
Librux Runtime Kernel for Robotics development
Librux Runtime Kernel for Robotics development

    API Contract Model

    API contract means one endpoint-level API contract for one semantic namespace.

    The public contract stack is this.

    Layer Meaning
    message typed payload schema
    API contract endpoint surfaces for one functional API namespace
    component named compatibility bundle for component-role subsystems, composed from one or more API contracts

    An API contract should be read as a coherent endpoint surface, not as a bag of unrelated methods.

    Endpoint Surfaces

    Each API contract may declare several endpoint surfaces.

    Endpoint kind Runtime shape Use for
    event publish / subscribe stream state, measurements, status, and telemetry
    control periodic timed exchange control packets with period, deadline, priority, and overrun sensitivity
    procedure bounded request / response non-periodic synchronous operations
    operation asynchronous operation with feedback, result, and state long-running commands

    The endpoint kind determines which payload slots are meaningful.

    Slot Used by
    request / args control, procedure, operation
    response control, procedure
    feedback operation
    result operation
    state operation, and sometimes a parallel event surface

    Namespace Groups

    Group Responsibility API Contract namespaces
    Articulated motion joint state, velocity control, and trajectory commands state, velocity, trajectory
    Manipulator motion task-space state, TCP velocity, tooling, and cartesian motion state, velocity, tooling, cartesian
    Locomotion body velocity, mobile-base state, and legged state velocity, mobile_base.state, legged.state
    Gateway surfaces actuator, camera, and low-level IO gateway surfaces actuator.servo, sensor.camera, io.digital.input, io.digital.output, io.analog
    Robot-level systems localization, mapping, navigation, and perception localization, mapping, navigation, perception

    Reading Rules

    • Match API contract namespaces with message namespaces whenever possible.
    • Use event for observable state and measurements.
    • Use control for periodic packets that need period, deadline, and overrun semantics.
    • Use procedure for bounded non-periodic request / response operations.
    • Use operation for long-running operations where callers need feedback, result, and state.
    • Compose components from API contracts instead of duplicating the same endpoint surface under component-specific names.

    Reference