Services

Basic Syntax

service MathInteraction(leftOperand: i4) {
    Add(rightOperand: i4): i4;
    Mul(rightOperand: i4): i4;
}

A service has:

• Name — identifier for the service interface
• Base arguments — shared parameters for all methods (in parentheses after the name)
• Methods — named RPC operations with typed parameters and return type

Base Arguments

Base arguments are declared in the service header and are automatically prepended to every method call. They act like a constructor or context that applies to all methods:

service UserService(spaceId: u4, auth: string) {
    GetUser(userId: u4): User;
    // On the wire, GetUser actually sends: [spaceId, auth, userId]
}

In C#, base arguments become constructor parameters. In TypeScript, they are passed when creating the service client.

Method Types

Unary (default)

Standard request-response. One request, one response over HTTP POST:

service DataService() {
    Do(data: bytes);           // void return
    DoIt(data: bytes): bytes;  // returns bytes
}

Route: POST /ion/DataService/DoIt.unary

Server Streaming

The stream modifier on the return type creates a server-streaming method over WebSocket:

service EventService(seed: i4) {
    stream Integer(i: i4): i4;
}

In C#, the return type becomes IAsyncEnumerable<i4>. Route: /ion/EventService/Integer.ws

Bidirectional Streaming

Add the stream modifier to a parameter for bidirectional streaming:

service StreamService(seed: i4) {
    stream Floats(stream i: f4): f4;
}

Both the input parameter and the return are streams. Only one parameter per method can be marked as stream (violation: ION0013).

Internal Methods

Methods marked internal are not exposed in public interfaces:

service AdminService() {
    internal Migrate(): void;
}

Void Methods

Methods that don't return a value omit the return type or use void:

service NotificationService() {
    SendNotification(userId: u4, text: string);  // void — no return type
}

Generated Code

A service generates multiple artifacts:

Real-World Example

msg Vector {
    x: f4;
    y: f4;
    z: f4;
}

service VectorMathInteraction(leftOperand: Vector) {
    Abs(): Vector;
    Add(rightOperand: Vector): Vector;
    Clamp(min: Vector, max: Vector): Vector;
}