HTTP protocol bindings¶

http trait¶

Summary

Configures the HTTP bindings of an operation.

Trait selector

operation

Value type

structure

The http trait is a structure that supports the following members:

The following example defines an operation that uses HTTP bindings:

namespace smithy.example

@idempotent
@http(method: "PUT", uri: "/{bucketName}/{key}", code: 200)
operation PutObject {
    input: PutObjectInput
}

structure PutObjectInput {
    // Sent in the URI label named "key".
    @required
    @httpLabel
    key: ObjectKey,

    // Sent in the URI label named "bucketName".
    @required
    @httpLabel
    bucketName: String,

    // Sent in the X-Foo header
    @httpHeader("X-Foo")
    foo: String,

    // Sent in the query string as paramName
    @httpQuery("paramName")
    someValue: String,

    // Sent in the body
    data: MyBlob,

    // Sent in the body
    additional: String,
}

@readonly
@http(method: "GET", uri: "/foo/{baz}")
operation GetService {
    output: GetServiceOutput
}

httpError trait¶

Summary

Defines an HTTP response code for an operation error.

Trait selector

structure[trait|error]

Structure shapes that also have the error trait

Value type

integer value (e.g., 404).

The httpError trait can only be applied to structures that also have the error trait.

By default, error structures with no httpError trait use the default HTTP status code of the error trait value. The httpError trait can be used to set a custom HTTP response status code.

@error("client")
@httpError(404)
structure MyError {}

httpHeader trait¶

Summary

Binds a structure member to an HTTP header.

Trait selector

:test(
    member:of(structure) > :test(
        boolean, number, string, timestamp,
        collection > member > :test(boolean, number, string, timestamp)
    )
)

Structure members that target boolean, number, string, or timestamp; or a structure member that targets a list/set of these types

Value type

string value defining the field name of the HTTP header. The value MUST NOT be empty and MUST be case-insensitively unique across all other members of the structure.

Conflicts with

httpLabel trait, httpQuery trait, httpPrefixHeaders trait, httpPayload trait

Serialization rules:

• The header field name MUST be compatible with RFC 7230#section-3.2.
• When a list shape is targeted, each member of the shape is serialized as a separate HTTP header either by concatenating the values with a comma on a single line or by serializing each header value on its own line.
• boolean values are serialized as true or false.
• blob values are base-64 encoded.
• string values with a mediaType trait of "application/json" or that end in "+json" are base-64 encoded.
• timestamp values are serialized using the http-date format as defined in the IMF-fixdate production of RFC 7231#section-7.1.1.1.

httpLabel trait¶

Summary

Binds an operation input structure member to an HTTP label.

Trait selector

:test(
    member:of(structure) > :test(
        string, number, boolean, timestamp
    )
)

Structure members that target any simple type other than blobs

Value type

Annotation trait.

Conflicts with

httpHeader trait, httpQuery trait, httpPrefixHeaders trait, httpPayload trait

httpLabel members MUST be marked as required trait.

When a structure is associated with an operation, any member of the structure with the httpLabel trait MUST have a corresponding URI label with the same name as the member. httpLabel traits are ignored when serializing the output or an error of an operation.

httpLabel traits can only be applied to structure members that are marked as required trait.

If the corresponding URI label in the operation is not greedy, then the httpLabel trait MUST target a string, byte, short, integer, long, float, double, bigDecimal, bigInteger, boolean, or timestamp. If the corresponding URI label in the operation is greedy, then the httpLabel trait MUST target a string shape.

Serialization rules:

• boolean is serialized as true or false.
• timestamp values are serialized as an RFC 3339 string (e.g., 1990-12-31T23:59:60Z).
• Unless the label is greedy, "/" MUST be percent encoded.

namespace smithy.example

@readonly
@http(method: "GET", uri: "/{foo}")
operation GetStatus {
    input: GetStatusInput,
    output: GetStatusOutput
}

structure GetStatusInput {
    @required
    @httpLabel
    foo: String
}

httpPayload trait¶

Summary

Binds a single structure member to the body of an HTTP request.

Trait selector

:test(
    member:of(structure) > :test(
        string, blob, structure, union
    )
)

Structure members that target a string, blob, structure, or union

Value type

Annotation trait.

Conflicts with

httpLabel trait, httpQuery trait, httpHeader trait, httpPrefixHeaders trait

By default, all structure members that are not bound as part of the HTTP message are serialized in a protocol-specific document sent in the body of the message (e.g., a JSON object). The httpPayload trait can be used to bind a single top-level operation input, output, or error structure member to the body of the HTTP message. Multiple members of the same structure MUST NOT be bound to httpPayload.

If the httpPayload trait is present on the structure referenced by the input of an operation, then all other structure members MUST be bound with the httpLabel trait, httpHeader trait, httpPrefixHeaders trait, or httpQuery trait.

If the httpPayload trait is present on the structure referenced by the output of an operation or a structure targeted by the error trait, then all other structure members MUST be bound to a httpHeader trait or httpPrefixHeaders trait.

Serialization rules:

1. When a string or blob member is referenced, the raw value is serialized as the body of the message.
2. When a structure or union is targeted, the shape value is serialized as a protocol-specific document that is sent as the body of the message.

httpPrefixHeaders trait¶

Summary

Binds a map of key-value pairs to prefixed HTTP headers.

Trait selector

:test(
    member:of(structure) > map > member[id|member=value] > :test(
        simpleType,
        collection > member > simpleType
    )
)

Structure member that targets a map of simple types or a map of [simple types]

Value type

string value that defines the prefix to prepend to each header field name stored in the targeted map member. For example, given a prefix value of of "X-Amz-Meta-" and a map key entry of "Baz", the resulting header field name serialized in the message is "X-Amz-Meta-Baz".

Conflicts with

httpLabel trait, httpQuery trait, httpHeader trait, httpPayload trait

In order to differentiate httpPrefixHeaders from other headers, when httpPrefixHeaders are used, no other httpHeader trait bindings can start with the same prefix provided in httpPrefixHeaders trait. If httpPrefixHeaders is set to an empty string, then no other members can be bound to headers.

Only a single structure member can be bound to httpPrefixHeaders.

Given the following Smithy model:

@readonly
@http(method: "GET", uri: "/myOperation")
operation MyOperation {
    input: MyOperationInput
}

structure MyOperationInput {
    @httpPrefixHeaders("X-Foo-")
    headers: StringMap
}

map StringMap {
    key: String,
    value: String
}

And given the following input to MyOperation:

{
    "headers": {
        "first": "hi",
        "second": "there"
    }
}

An example HTTP request would be serialized as:

GET /myOperation
Host: <server>
X-Foo-first: hi
X-Foo-second: there

httpQuery trait¶

Summary

Binds an operation input structure member to a query string parameter.

Trait selector

:test(
    member:of(structure) > :test(
        simpleType,
        collection > member > simpleType
    )
)

Structure members that target simple types or lists/sets of simple types

Value type

string value defining the name of the query string parameter. The query string value MUST NOT be empty. This trait is ignored when resolving the HTTP bindings of an operation's output or an error.

Conflicts with

httpLabel trait, httpHeader trait, httpPrefixHeaders trait, httpPayload trait

Serialization rules:

• "&" is used to separate query string parameters.
• "=" is used to separate query string parameter names from values.
• Query string keys and values MUST be percent-encoded so that they conform to the query grammar defined in RFC 3986#section-3.4. Characters that are valid as part of the query string MUST NOT be percent encoded. For example, a value of foo/baz%20 serialized in a query string would become foo/baz%2520. However, & MUST be percent-encoded when present in a query string value.
• Multiple members of a structure MUST NOT case-sensitively target the same query string parameter.
• boolean values are serialized as true or false.
• blob values are base-64 encoded when serialized in the query string.
• timestamp values are serialized as an RFC 3339 date-time string (e.g., 1990-12-31T23:59:60Z).
• list members are serialized by adding multiple query string parameters to the query string using the same name. For example, given a member bound to foo that targets a list of strings with a value of ["a", "b"], the value is serialized in the query string as foo=a&foo=b.

cors trait¶

Summary

Defines how a service supports cross-origin resource sharing

Trait selector

service

Value type

structure

The cors trait is a structure that supports the following members:

Adding a cors trait with its value set to an empty object enables cross-origin resource sharing for all origins and allows browser scripts access to all headers to which data is bound in the model, as well as any headers used by the protocol and authentication scheme.

The default settings are not compatible with certain authentication schemes (e.g., http-basic) that rely on browser-managed credentials. Services using such authentication schemes MUST designate a single origin from which cross-origin, credentialed requests will be accepted.

Serializing HTTP messages¶

The following steps are taken to serialize an HTTP request given a map of parameters:

1. Set the HTTP method to the method property of the http trait of the operation.
2. Set the URI of the HTTP request to the uri property of the http trait.
3. Iterate over all of the key-value pairs of the parameters and find the corresponding structure member by name:
   1. If the member has the httpLabel trait, expand the value into the URI.
   2. If the member has the httpQuery trait, serialize the value into the HTTP request as a query string parameter.
   3. If the member has the httpHeader trait, serialize the value in an HTTP header using the value of the httpHeader trait.
   4. If the member has the httpPrefixHeaders trait and the value is a map, serialize the map key value pairs as prefixed HTTP headers.
   5. If the member has the httpPayload trait, serialize the value as the body of the request.
   6. If the member has no bindings, serialize the key-value pair as part of a protocol-specific document sent in the body of the request.

The following steps are taken to serialize an HTTP response given a map of parameters:

1. If serializing the output of an operation, set the status code of the response to the code property of the http trait.
2. If serializing an error and the the httpError trait is present, set the status code of the response to its value. Otherwise, set the status code to 400 if the error trait is "client" or to 500 if the error trait is "server".
3. Iterate over all of the key-value pairs of the parameters and find the corresponding structure member by name:
   1. If the member has the httpHeader trait, serialize the value in an HTTP header using the value of the httpHeader trait.
   2. If the member has the httpPrefixHeaders trait and the value is a map, serialize the map key value pairs as prefixed HTTP headers.
   3. If the member has the httpPayload trait, serialize the value as the body of the response.
   4. If the member has no bindings, serialize the key-value pair as part of a protocol-specific document sent in the body of the response.

Event streams¶

When using event streams and HTTP bindings, the httpPayload trait MUST be applied to any input or output member targeted by the eventStream trait.

The following example defines an operation that uses an input event stream and HTTP bindings:

namespace smithy.example

@http(method: "POST", uri: "/messages")
operation PublishMessages {
    input: PublishMessagesInput
}

structure PublishMessagesInput {
    @httpPayload
    @eventStream
    messages: Message,
}

structure Message {
    message: String,
}

{
    "smithy": "0.5.0",
    "shapes": {
        "smithy.example#PublishMessages": {
            "type": "operation",
            "input": {
                "target": "smithy.example#PublishMessagesInput"
            },
            "traits": {
                "smithy.api#http": {
                    "uri": "/messages",
                    "method": "POST"
                }
            }
        },
        "smithy.example#PublishMessagesInput": {
            "type": "structure",
            "members": {
                "messages": {
                    "target": "smithy.example#Message",
                    "traits": {
                        "smithy.api#httpPayload": true,
                        "smithy.api#eventStream": true
                    }
                }
            }
        },
        "smithy.example#Message": {
            "type": "structure",
            "members": {
                "message": {
                    "target": "smithy.api#String"
                }
            }
        }
    }
}

The following is invalid because the operation has the http trait and an input member is marked with the eventStream trait but not marked with the httpPayload trait:

namespace smithy.example

@http(method: "POST", uri: "/messages")
operation InvalidOperation {
    input: InvalidOperationInput
}

structure InvalidOperationInput {
    @eventStream
    invalid: Message, // <-- Missing the @httpPayload trait
}