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.

Layering on HTTP

Protocol details are traits, not part of the operation’s structure. @http binds the operation to an HTTP method, URI, and status code; members can bind to the URL path (@httpLabel) or the query string (@httpQuery):

@readonly
@http(method: "GET", uri: "/cities/{cityId}", code: 200)
operation GetCity {
    input := {
        @required
        @httpLabel
        cityId: String

        @httpQuery("verbose")
        verbose: Boolean
    }

    output := {
        @required
        name: String
    }
}

Every {placeholder} in the URI must match a @required @httpLabel member.

Your turn