From 01977142518696972f06cc186a5217f1abc0d9b0 Mon Sep 17 00:00:00 2001 From: kstich Date: Tue, 5 Apr 2022 10:28:40 -0700 Subject: [PATCH] Update AWS protocol documentation This commit updates the awsJson1_0 and awsJson1_1 documentation to include their http and eventStreamHttp properties. These cannot be templated, because substitutions in code blocks aren't valid. Additionally, it removes a misleading note from the ec2Query docs. --- .../1.0/spec/aws/aws-ec2-query-protocol.rst | 5 -- .../1.0/spec/aws/aws-json-1_0-protocol.rst | 83 ++++++++++++++++++- .../1.0/spec/aws/aws-json-1_1-protocol.rst | 83 ++++++++++++++++++- .../1.0/spec/aws/aws-restjson1-protocol.rst | 13 ++- 4 files changed, 173 insertions(+), 11 deletions(-) diff --git a/docs/source/1.0/spec/aws/aws-ec2-query-protocol.rst b/docs/source/1.0/spec/aws/aws-ec2-query-protocol.rst index 0628d394fcc..72fb44779fa 100644 --- a/docs/source/1.0/spec/aws/aws-ec2-query-protocol.rst +++ b/docs/source/1.0/spec/aws/aws-ec2-query-protocol.rst @@ -35,11 +35,6 @@ Value type This protocol does not support document types. -.. important:: - - This protocol only permits the :ref:`httpPayload-trait` to be applied to - members that target structures, documents, strings, blobs, or unions. - .. tabs:: .. code-tab:: smithy diff --git a/docs/source/1.0/spec/aws/aws-json-1_0-protocol.rst b/docs/source/1.0/spec/aws/aws-json-1_0-protocol.rst index 073e2b2afae..1139a934b95 100644 --- a/docs/source/1.0/spec/aws/aws-json-1_0-protocol.rst +++ b/docs/source/1.0/spec/aws/aws-json-1_0-protocol.rst @@ -25,10 +25,40 @@ Summary Trait selector ``service`` Value type - Annotation trait. + Structure See `Protocol tests `_ +``aws.protocols#awsJson1_0`` is a structure that supports the following +members: + +.. list-table:: + :header-rows: 1 + :widths: 10 20 70 + + * - 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 :ref:`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``. + +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#awsJson1_0``. + .. tabs:: .. code-tab:: smithy @@ -57,8 +87,59 @@ See } } +The following example defines a service that requires the use of +``h2`` when using event streams. + +.. code-block:: smithy + + namespace smithy.example + + use aws.protocols#awsJson1_0 + + @awsJson1_0( + http: ["h2", "http/1.1"], + eventStreamHttp: ["h2"] + ) + service MyService { + version: "2020-02-05" + } + +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``. + +.. code-block:: smithy + + namespace smithy.example + + use aws.protocols#awsJson1_0 + + @awsJson1_1( + http: ["h2", "http/1.1"], + eventStreamHttp: ["h2", "http/1.1"] + ) + service MyService { + version: "2020-02-05" + } + +The following example defines a service that requires the use of +``h2`` for all requests, including event streams. + +.. code-block:: smithy + + namespace smithy.example + + use aws.protocols#awsJson1_0 + + @awsJson1_0(http: ["h2"]) + service MyService { + version: "2020-02-05" + } + .. |quoted shape name| replace:: ``awsJson1_0`` .. |protocol content type| replace:: ``application/x-amz-json-1.0`` .. |protocol error type contents| replace:: :ref:`shape-id` .. |protocol test link| replace:: https://github.com/awslabs/smithy/tree/main/smithy-aws-protocol-tests/model/awsJson1_0 .. include:: aws-json.rst.template + +.. _`Application-Layer Protocol Negotiation (ALPN) Protocol ID`: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids diff --git a/docs/source/1.0/spec/aws/aws-json-1_1-protocol.rst b/docs/source/1.0/spec/aws/aws-json-1_1-protocol.rst index 88c593779d5..b88bddf4e10 100644 --- a/docs/source/1.0/spec/aws/aws-json-1_1-protocol.rst +++ b/docs/source/1.0/spec/aws/aws-json-1_1-protocol.rst @@ -25,10 +25,40 @@ Summary Trait selector ``service`` Value type - Annotation trait. + Structure See `Protocol tests `_ +``aws.protocols#awsJson1_1`` is a structure that supports the following +members: + +.. list-table:: + :header-rows: 1 + :widths: 10 20 70 + + * - 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 :ref:`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``. + +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#awsJson1_1``. + .. tabs:: .. code-tab:: smithy @@ -57,8 +87,59 @@ See } } +The following example defines a service that requires the use of +``h2`` when using event streams. + +.. code-block:: smithy + + namespace smithy.example + + use aws.protocols#awsJson1_1 + + @awsJson1_1( + http: ["h2", "http/1.1"], + eventStreamHttp: ["h2"] + ) + service MyService { + version: "2020-02-05" + } + +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``. + +.. code-block:: smithy + + namespace smithy.example + + use aws.protocols#awsJson1_1 + + @awsJson1_1( + http: ["h2", "http/1.1"], + eventStreamHttp: ["h2", "http/1.1"] + ) + service MyService { + version: "2020-02-05" + } + +The following example defines a service that requires the use of +``h2`` for all requests, including event streams. + +.. code-block:: smithy + + namespace smithy.example + + use aws.protocols#awsJson1_1 + + @awsJson1_1(http: ["h2"]) + service MyService { + version: "2020-02-05" + } + .. |quoted shape name| replace:: ``awsJson1_1`` .. |protocol content type| replace:: ``application/x-amz-json-1.1`` .. |protocol error type contents| replace:: :token:`shape name ` .. |protocol test link| replace:: https://github.com/awslabs/smithy/tree/main/smithy-aws-protocol-tests/model/awsJson1_1 .. include:: aws-json.rst.template + +.. _`Application-Layer Protocol Negotiation (ALPN) Protocol ID`: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids diff --git a/docs/source/1.0/spec/aws/aws-restjson1-protocol.rst b/docs/source/1.0/spec/aws/aws-restjson1-protocol.rst index e6a89030005..f83812b84e5 100644 --- a/docs/source/1.0/spec/aws/aws-restjson1-protocol.rst +++ b/docs/source/1.0/spec/aws/aws-restjson1-protocol.rst @@ -98,7 +98,10 @@ The following example defines a service that requires the use of use aws.protocols#restJson1 - @restJson1(eventStreamHttp: ["h2"]) + @restJson1( + http: ["h2", "http/1.1"], + eventStreamHttp: ["h2"] + ) service MyService { version: "2020-04-02" } @@ -113,7 +116,10 @@ preferred over ``http/1.1``. use aws.protocols#restJson1 - @restJson1(eventStreamHttp: ["h2", "http/1.1"]) + @awsJson1_1( + http: ["h2", "http/1.1"], + eventStreamHttp: ["h2", "http/1.1"] + ) service MyService { version: "2020-04-02" } @@ -315,8 +321,7 @@ standard responses with one additional component to distinguish which error is contained. New server-side protocol implementations MUST use a header field named ``X-Amzn-Errortype``. Clients MUST accept any one of the following: an additional header with the name ``X-Amzn-Errortype``, a body field with the -name ``__type``, or a body field named ``code -``. The value of this component +name ``__type``, or a body field named ``code``. The value of this component SHOULD contain only the :token:`shape name ` of the error's :ref:`shape-id`.