AWS restXml protocol

This specification defines the aws.protocols#restXml protocol.

aws.protocols#restXml trait

Summary

Adds support for an HTTP-based protocol that sends XML requests and responses.

Trait selector

service

Value type

Structure

aws.protocols#restXml is a structure that supports the following members:

Property	Type	Description
http	[string]	The priority ordered list of supported HTTP protocol versions.
eventStreamHttp	[string]	The priority ordered list of supported HTTP protocol versions that are required when using event streams with the service. If not set, this value defaults to the value of the http member. Any entry in eventStreamHttp MUST also appear in http.
noErrorWrapping	boolean	Disables the wrapping of error properties in an ErrorResponse XML element. See operation error serialization for more information.

Each entry in http and eventStreamHttp SHOULD be a valid Application-Layer Protocol Negotiation (ALPN) Protocol ID (for example, http/1.1, h2, etc). Clients SHOULD pick the first protocol in the list they understand when connecting to a service. A client SHOULD assume that a service supports http/1.1 when no http or eventStreamHttp values are provided.

The following example defines a service that uses aws.protocols#restXml.

$version: "2"

namespace smithy.example

use aws.protocols#restXml

@restXml
service MyService {
    version: "2020-04-02"
}

The following example defines a service that requires the use of h2 when using event streams.

$version: "2"

namespace smithy.example

use aws.protocols#restXml

@restXml(eventStreamHttp: ["h2"])
service MyService {
    version: "2020-04-02"
}

The following example defines a service that requires the use of h2 or http/1.1 when using event streams, where h2 is preferred over http/1.1.

$version: "2"

namespace smithy.example

use aws.protocols#restXml

@restXml(eventStreamHttp: ["h2", "http/1.1"])
service MyService {
    version: "2020-04-02"
}

The following example defines a service that requires the use of h2 for all requests, including event streams.

$version: "2"

namespace smithy.example

use aws.protocols#restXml

@restXml(http: ["h2"])
service MyService {
    version: "2020-04-02"
}

Supported traits

The aws.protocols#restXml protocol supports the following traits that affect serialization:

Trait	Description
cors	Indicates that the service supports CORS.
endpoint	Configures a custom operation endpoint.
hostLabel	Binds a top-level operation input structure member to a label in the hostPrefix of an endpoint trait.
http	Configures the HTTP bindings of an operation. An operation bound to a service with this protocol applied MUST have the http trait applied.
httpError	A client error has a default status code of 400, and a server error has a default status code of 500. The httpError trait is used to define a custom status code.
httpHeader	Binds a top-level input, output, or error structure member to an HTTP header instead of the payload.
httpLabel	Binds a top-level input structure member to a URI label instead of the payload.
httpPayload	Binds a top-level input or output structure member as the payload of a request or response.
httpPrefixHeaders	Binds a top-level input, output, or error member to a map of prefixed HTTP headers.
httpQuery	Binds a top-level input structure member to a query string parameter.
httpQueryParams	Binds a map of key-value pairs to query string parameters.
httpChecksumRequired	Indicates that requests MUST send a checksum.
xmlAttribute	Serializes an object property as an XML attribute rather than a nested XML element.
xmlFlattened	By default, entries in lists, sets, and maps have values serialized in nested XML elements specific to their type. The xmlFlattened trait unwraps these elements into the containing structure.
xmlName	By default, the XML element names used in serialized structures are the same as a structure member name. The xmlName trait changes the XML element name to a custom value.
xmlNamespace	Adds an xmlns namespace definition URI to XML element(s) generated for the targeted shape.
timestampFormat	Defines a custom timestamp serialization format.
requestCompression	Indicates that an operation supports compressing requests from clients to services.

Important

This protocol does not support document types.

Content-Type

The aws.protocols#restXml protocol uses a default Content-Type of application/xml.

Input or output shapes that apply the httpPayload trait on one of their top-level members MUST use a Content-Type that is appropriate for the payload. The following table defines the expected Content-Type header for requests and responses based on the shape targeted by the member marked with the httpPayload trait:

Targeted shape	Content-Type
Has mediaType trait	Use the value of the mediaType trait if present.
string	text/plain
blob	application/octet-stream
document	Undefined. Document shapes are not supported in this protocol.
structure	application/xml
union	application/xml

Default value serialization

1. To avoid information disclosure, serializers SHOULD omit the default value of structure members that are marked with the internal trait.
2. Client deserializers SHOULD attempt to error correct structures that omit a @required member by filling in a default zero value for the member. Error correction allows clients to continue to function while the server is in error.

XML shape serialization

Smithy type	XML entity
blob	XML text node with a value that is base64 encoded.
boolean	XML text node with a value either "true" or "false".
byte	XML text node with a value of the number.
short	XML text node with a value of the number.
integer	XML text node with a value of the number.
long	XML text node with a value of the number.
float	XML text node with a value of the number.
double	XML text node with a value of the number.
bigDecimal	XML text node with a value of the number, using scientific notation if an exponent is needed. Unfortunately, many XML parsers will either truncate the value or be unable to parse numbers that exceed the size of a double.
bigInteger	XML text node with a value of the number, using scientific notation if an exponent is needed. Unfortunately, many XML parsers will either truncate the value or be unable to parse numbers that exceed the size of a double.
string	XML text node with an XML-safe, UTF-8 value of the string.
timestamp	XML text node with a value of the timestamp. This protocol uses date-time as the default serialization. However, the timestampFormat MAY be used to customize timestamp serialization.
document	Undefined. Document shapes are not supported in this protocol.
list	XML element. Each value provided in the list is serialized as a nested XML element with the name member. The xmlName trait can be used to serialize a property using a custom name. The xmlFlattened trait can be used to unwrap the values into a containing structure or union, with the value XML element using the structure or union member name. See List serialization for more.
map	XML element. Each key-value pair provided in the map is serialized in a nested XML element with the name entry that contains nested elements key and value for the pair. The xmlName trait can be used to serialize key or value properties using a custom name, it cannot be used to influence the entry name. The xmlFlattened trait can be used to unwrap the entries into a containing structure or union, with the entry XML element using the structure or union member name. See Map serialization for more.
structure	XML element. Each member value provided for the structure is serialized as a nested XML element where the element name is the same as the member name. The xmlName trait can be used to serialize a property using a custom name. The xmlAttribute trait can be used to serialize a property in an attribute of the containing element. See Structure and union serialization for more.
union	XML element. A union is serialized identically to a structure shape, but only a single member can be set to a non-null value.

Important

See XML bindings for comprehensive documentation, including examples and behaviors when using multiple XML traits.

HTTP binding serialization

The aws.protocols#restXml protocol supports all of the HTTP binding traits defined in the HTTP protocol bindings specification. The serialization formats and behaviors described for each trait are supported as defined in the aws.protocols#restXml protocol.

Non-numeric float and double serialization

Smithy floats and doubles are defined by IEEE-754, which includes special values for "not a number" and both positive and negative infinity. Unless otherwise specified, the aws.protocols#restXml protocol treats those special values as strings with the following values:

Special Value	String Value
Not a number	NaN
Positive infinity	Infinity
Negative infinity	-Infinity

Error response serialization

Error responses in the restXml protocol are wrapped within an XML root node named ErrorResponse by default. A nested element, named Error, contains the serialized error structure members, unless bound to another location with HTTP protocol bindings.

Serialized error shapes MUST also contain an additional child element Code that contains only the shape name of the error's Shape ID. This can be used to distinguish which specific error has been serialized in the response.

<ErrorResponse>
    <Error>
        <Type>Sender</Type>
        <Code>InvalidGreeting</Code>
        <Message>Hi</Message>
        <AnotherSetting>setting</AnotherSetting>
    </Error>
    <RequestId>foo-id</RequestId>
</ErrorResponse>

The noErrorWrapping setting of the restXml protocol trait disables using this additional nested XML element as the root node.

<Error>
    <Type>Sender</Type>
    <Code>InvalidGreeting</Code>
    <Message>Hi</Message>
    <AnotherSetting>setting</AnotherSetting>
    <RequestId>foo-id</RequestId>
</Error>

Error responses contain the following nested elements:

• Error: A container for the encountered error.
• Type: One of "Sender" or "Receiver"; whomever is at fault from the service perspective.
• Code: The shape name of the error's Shape ID.
• RequestId: Contains a unique identifier for the associated request.

In the above example, Message, and AnotherSetting are additional, hypothetical members of the serialized error structure.

Protocol compliance tests

A full compliance test suite is provided and SHALL be considered a normative reference: https://github.com/smithy-lang/smithy/tree/main/smithy-aws-protocol-tests/model/restXml

These compliance tests define a model that is used to define test cases and the expected serialized HTTP requests and responses for each case.

TODO: Add event stream handling specifications.

Error shape renaming

By default, Smithy permits renaming shapes to disambiguate shape ID conflicts in the service closure via the rename property. However, services using this protocol are not allowed to rename error shapes (shapes with error trait applied).

Client-side implementations rely on the response body field code or __type to resolve the error type. Server-side implementations of this protocol will only send the shape name for the response body field.

When there are conflicting shape IDs smithy.service#ServiceError and smithy.other#ServiceError, the server will only send the shape name ServiceError. Clients will not be able to resolve the correct error type without the namespace.

Server-side implementations of this protocol don't serialize renamed shape names. As a result, renaming will not resolve the conflicting shape IDs issue, and hence it is not permitted.