From 5847a4b8870464a98f48b66554dacfeb5a0b7c35 Mon Sep 17 00:00:00 2001 From: John DiSanti Date: Wed, 9 Jun 2021 09:47:19 -0700 Subject: [PATCH 1/2] Improve EC2 Query spec documentation - Clarify protocol HTTP request behavior - Remove all non-flattened query names since EC2 Query automatically flattens all collections and maps in requests (as opposed to AWS Query where you have to opt in to flattening with `@xmlFlattened`) - Fix query capitalization in examples - Remove nested `Result` tag from response documentation - Add `Response` wrapper to error response example --- .../1.0/spec/aws/aws-ec2-query-protocol.rst | 86 +++++++------------ 1 file changed, 30 insertions(+), 56 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 9ddb695c5c8..6dcb53fe0c7 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 @@ -19,9 +19,10 @@ This specification defines the ``aws.protocols#ec2`` protocol. -------------------------------- Summary - Adds support for an HTTP protocol that sends requests in the query string - OR in a ``x-form-url-encoded`` body and responses in XML documents. This - protocol is an Amazon EC2-specific extension of the ``awsQuery`` protocol. + Adds support for an HTTP protocol that sends requests in a + ``application/x-www-form-url-encoded`` body and responses in XML + documents. This protocol is an Amazon EC2-specific extension + of the ``awsQuery`` protocol. Trait selector ``service [trait|xmlNamespace]`` @@ -145,8 +146,7 @@ resolved using the following process: member, if present. 2. Use the value of the :ref:`xmlName trait ` applied to the member with the first letter capitalized, if present. -3. Use the default value for the member with the first letter capitalized, if - present: +3. Use the default value for the member, if present: .. list-table:: :header-rows: 1 @@ -154,18 +154,10 @@ resolved using the following process: * - Member location - Default value - * - ``list`` member - - The string literal "member" - * - ``set`` member - - The string literal "member" - * - ``map`` key - - The string literal "key" - * - ``map`` value - - The string literal "value" * - ``structure`` member - - The :token:`member name ` + - The :token:`member name ` capitalized * - ``union`` member - - The :token:`member name ` + - The :token:`member name ` capitalized ---------------- @@ -266,11 +258,11 @@ The ``x-www-form-urlencoded`` serialization is: Action=Ec2QueryStructures &Version=2020-07-02 - &foo=bar + &Foo=bar &A=example0 &B=example1 &C=example2 - &baz.temp=example3 + &Baz.Temp=example3 Collections @@ -286,21 +278,9 @@ For example, given the following: ListArg: StringList, ComplexListArg: GreetingList, - @xmlFlattened - FlattenedListArg: StringList, - - ListArgWithXmlNameMember: ListWithXmlName, - - // Notice that the xmlName on the targeted list member is ignored. - @xmlFlattened - @ec2QueryName("Hi") + @ec2QueryName("Renamed") @xmlName("IgnoreMe") - FlattenedListArgWithXmlName: ListWithXmlName, - } - - list ListWithXmlName { - @xmlName("item") - member: String + RenamedListArg: StringList, } list StringList { @@ -315,23 +295,19 @@ For example, given the following: hi: String, } -The ``x-www-form-urlencoded`` serialization is: +The ``application/x-www-form-urlencoded`` serialization is: .. code-block:: text Action=Ec2QueryLists &Version=2020-07-02 - &ListArg.member.1=foo - &ListArg.member.2=bar - &ListArg.member.3=baz - &ComplexListArg.member.1.hi=hello - &ComplexListArg.member.2.hi=hola - &FlattenedListArg.1=A - &FlattenedListArg.2=B - &ListArgWithXmlNameMember.item.1=A - &ListArgWithXmlNameMember.item.2=B - &Hi.1=A - &Hi.2=B + &ListArg.1=foo + &ListArg.2=bar + &ListArg.3=baz + &ComplexListArg.1.Hi=hello + &ComplexListArg.2.Hi=hola + &Renamed.1=A + &Renamed.2=B ---------------------- @@ -339,8 +315,7 @@ Response serialization ---------------------- The ``ec2Query`` protocol serializes XML responses within an XML root node with -the name of the operation's output suffixed with "Response". A nested element, -with the name of the operation's output suffixed with "Result", contains the +the name of the operation's output suffixed with "Response", which contains the contents of the successful response. The value of the ``uri`` member of the :ref:`xmlNamespace trait ` @@ -350,9 +325,7 @@ following is a sample response to an operation named ``XmlTest``. .. code-block:: xml - - Hello! - + Hello! XML shape serialization @@ -378,15 +351,16 @@ serialized in the response. .. code-block:: xml - - - Sender - InvalidGreeting - Hi - setting - + + + + InvalidGreeting + Hi + setting + + foo-id - + .. _ec2Query-compliance-tests: From 5373e2c67817537a88d72d3e00ae3139f3b20894 Mon Sep 17 00:00:00 2001 From: John DiSanti Date: Wed, 9 Jun 2021 10:55:32 -0700 Subject: [PATCH 2/2] Fix blurb describing EC2 Query error shape --- docs/source/1.0/spec/aws/aws-ec2-query-protocol.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 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 6dcb53fe0c7..c9c8b0adc8b 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 @@ -341,8 +341,10 @@ Operation error serialization ----------------------------- Error responses in the ``ec2Query`` protocol are wrapped within an XML root -node named ``Errors``. A nested element, named ``Error``, contains the -serialized error structure members. +node named ``Response``. Inside this, there is an ``Errors`` tag containing +the actual error, and a ``RequestId`` tag holding the request ID. Nested inside +of the ``Errors`` tag is an ``Error`` tag which contains the serialized error +structure members. Serialized error shapes MUST also contain an additional child element ``Code`` that contains only the :token:`shape name ` of the error's