Services & operations

Up to now we’ve modeled data. Now we model behavior. A service is the top-level API; it has a version and lists its operations.

service CityService {
    version: "2024-01-01"
    operations: [
        GetCity
    ]
}

A service must declare a version. Forgetting it is an assembler error.

Operations

An operation has at most one input, one output, and a list of errors. Smithy 2.0’s input := { ... } / output := { ... } syntax declares the input/output structure inline and binds it in one step:

@readonly
operation GetCity {
    input := {
        @required
        cityId: String
    }

    output := {
        @required
        name: String
    }
}

@readonly marks the operation as having no side effects. (HTTP bindings come in the next lesson — an operation is protocol-agnostic on its own.)

When you write input := { ... }, Smithy synthesizes a structure named <Operation>Input — here GetCityInput — and a member check therefore targets example#GetCityInput$cityId.