9. Behavior traits#

9.1. Idempotency#

Operations marked with the readonly trait or idempotent trait are considered idempotent as defined in RFC 7231#section-4.2.2. Operations that contain a top-level input member marked with the idempotencyToken trait that are provided a token for the member are also considered idempotent. All other operations SHOULD be considered unsafe to retry unless the response to the operation is an error marked with the retryable trait or another kind of protocol-specific hint indicates the operation is safe to retry (for example, a Retry-After HTTP header, a 503 HTTP response, or a 429 HTTP response).

9.1.1. idempotencyToken trait#

Summary
Defines the input member of an operation that is used by the server to identify and discard replayed requests.
Trait selector

structure > :test(member > string)

Any structure member that targets a string

Value type
Annotation trait

Only a single member of the input of an operation can be targeted by the idempotencyToken trait; only top-level structure members of the input of an operation are considered.

A unique identifier (typically a UUID) SHOULD be used by the client when providing the value for the request token member. When the request token is present, the service MUST ensure that the request is not replayed within a service-defined period of time. This allows the client to safely retry operation invocations, including operations that are not read-only, that fail due to networking issues or internal server errors. The service uses the provided request token to identify and discard duplicate requests.

Client implementations MAY automatically provide a value for a request token member if and only if the member is not explicitly provided.

operation AllocateWidget {
    input: AllocateWidgetInput
}

@input
structure AllocateWidgetInput {
    @idempotencyToken
    clientToken: String
}

9.1.2. idempotent trait#

Summary
Indicates that the intended effect on the server of multiple identical requests with an operation is the same as the effect for a single such request.
Trait selector
operation
Value type
Annotation trait
Conflicts with
readonly trait
@idempotent
operation DeleteSomething {
    input: DeleteSomethingInput
    output: DeleteSomethingOutput
}

Note

All operations that are marked as readonly trait are inherently idempotent.

9.1.3. readonly trait#

Summary
Indicates that an operation is effectively read-only.
Trait selector
operation
Value type
Annotation trait
Conflicts with
idempotent trait
@readonly
operation GetSomething {
    input: GetSomethingInput
    output: GetSomethingOutput
}

9.1.4. retryable trait#

Summary
Indicates that an error MAY be retried by the client.
Trait selector

structure[trait|error]

A structure shape with the error trait

Value type
structure

The retryable trait is a structure that contains the following members:

Property Type Description
throttling boolean Indicates that the error is a retryable throttling error.
@error("server")
@retryable
@httpError(503)
structure ServiceUnavailableError {}

@error("client")
@retryable(throttling: true)
@httpError(429)
structure ThrottlingError {}