Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Better describe AWS XML protocols #827

Merged
merged 1 commit into from
Jun 10, 2021
+256 −180
Merged

Better describe AWS XML protocols #827

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions docs/source/1.0/spec/aws/aws-ec2-query-protocol.rst
View file
Original file line number Diff line number Diff line change
@@ -364,6 +364,13 @@ serialized in the response.
<RequestId>foo-id</RequestId>
</Response>
* ``Code``: The :token:`shape name <identifier>` of the error's
:ref:`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.


.. _ec2Query-compliance-tests:

369 changes: 225 additions & 144 deletions docs/source/1.0/spec/aws/aws-query-protocol.rst
View file
Original file line number Diff line number Diff line change
@@ -4,138 +4,51 @@
AWS query protocol
==================

This specification defines the ``aws.protocols#awsQuery`` protocol.
This document defines the ``aws.protocols#awsQuery`` protocol.

.. contents:: Table of contents
:depth: 2
:local:
:backlinks: none


.. _aws.protocols#awsQuery-trait:

--------------------------------
``aws.protocols#awsQuery`` trait
--------------------------------

Summary
Adds support for an HTTP protocol that sends "POST" requests in the body
as ``x-www-form-urlencoded`` strings and responses in XML documents.
Trait selector
``service [trait|xmlNamespace]``

*Service shapes with the xmlNamespace trait*
Value type
Annotation trait.
See
`Protocol tests <https://github.com/awslabs/smithy/tree/__smithy_version__/smithy-aws-protocol-tests/model/awsQuery>`_

.. tabs::

.. code-tab:: smithy

namespace smithy.example

use aws.protocols#awsQuery

@awsQuery
service MyService {
version: "2020-02-05"
}

.. code-tab:: json

{
"smithy": "1.0",
"shapes": {
"smithy.example#MyService": {
"type": "service",
"version": "2020-02-05",
"traits": {
"aws.protocols#awsQuery": {}
}
}
}
}

.. _aws.protocols#awsQueryError-trait:
--------
Overview
--------

-------------------------------------
``aws.protocols#awsQueryError`` trait
-------------------------------------
The AWS Query protocol uses HTTP and serializes HTTP requests using query
string parameters and responses using XML. Requests can be sent using GET
requests and placing parameters in the query string; however, sending
requests using POST with an ``application/x-www-form-urlencoded``
Content-Type is preferred because some proxies, clients, and servers have
limitations around the maximum amount of data that can be sent in a query
string.

Summary
Provides a :ref:`custom "Code" value <awsQuery-error-code>` for
``awsQuery`` errors and an :ref:`HTTP response code <awsQuery-error-response-code>`.
The "Code" of an ``awsQuery`` error is used by clients to determine which
type of error was encountered.
Trait selector
``structure [trait|error]``
A service is configured to use this protocol by applying the :ref:`aws.protocols#awsQuery-trait`.
The service MUST also define the :ref:`xmlnamespace-trait` which is used
to determine the XML namespace used in XML responses.

The ``httpError`` trait can only be applied to :ref:`structure <structure>`
shapes that also have the :ref:`error-trait`.
Value type
``structure``
.. code-block:: smithy
The ``awsQueryError`` trait is a structure that supports the following members:
namespace smithy.example
.. list-table::
:header-rows: 1
:widths: 10 25 65
use aws.protocols#awsQuery
* - Property
- Type
- Description
* - code
- ``string``
- **Required** The value used to distinguish this error shape during
client deserialization.
* - httpResponseCode
- ``integer``
- **Required** The HTTP response code used on a response that contains
this error shape.
@awsQuery
@xmlNamespace(uri: "http://foo.com")
service MyService {
version: "2020-02-05"
}
.. important::
The ``aws.protocols#awsQueryError`` trait is only used when serializing
operation errors using the ``aws.protocols#query`` protocol.

.. tabs::
* This protocol is deprecated and SHOULD NOT be used for any new service.
* This protocol does not support document types.
* This protocol does not support :ref:`HTTP binding traits <http-traits>`.
HTTP binding traits MUST be ignored if they are present.
* This protocol does not support any kind of streaming requests or
responses, including event streams.

.. code-tab:: smithy

use aws.protocols#awsQueryError

@awsQueryError(
code: "InvalidThing",
httpResponseCode: 400,
)
@error("client")
structure InvalidThingException {
message: String
}

.. code-tab:: json

{
"smithy": "1.0",
"shapes": {
"smithy.example#InvalidThingException": {
"type": "structure",
"members": {
"message": {
"target": "smithy.api#String"
}
},
"traits": {
"aws.protocols#awsQueryError": {
"code": "InvalidThing",
"httpResponseCode": 400
},
"smithy.api#error": "client"
}
}
}
}

----------------
Supported traits
@@ -180,15 +93,11 @@ that affect serialization:
The "Code" of an ``awsQuery`` error is used by clients to determine
which type of error was encountered.

.. important::

This protocol does not support document types.


.. |quoted shape name| replace:: ``awsQuery``
.. |name resolution text| replace:: The :ref:`xmlName-trait` can be used to serialize a property using a custom name
.. include:: aws-query-serialization.rst.template


.. _aws.protocols#awsQueryName-query-key-naming:

Query key resolution
@@ -221,16 +130,15 @@ resolved using the following process:
- The :token:`member name <shape_id_member>`


Examples
--------

.. important::
Example requests
----------------

These examples are non-exhaustive. See the :ref:`awsQuery-compliance-tests`
for a suite of compliance tests for the ``awsQuery`` protocol.
The following list of examples are non-exhaustive. See the
:ref:`awsQuery-compliance-tests` for a suite of compliance tests for the
``awsQuery`` protocol. Newlines have been to examples only for readability.


Structures and Unions
Structures and unions
=====================

|query aggregate text|
@@ -252,10 +160,15 @@ For example, given the following:
temp: String,
}
The ``x-www-form-urlencoded`` serialization is:
The ``application/x-www-form-urlencoded`` serialization is:

.. code-block:: text
POST / HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: ...
Host: example.com
Action=QueryStructures
&Version=2020-07-02
&foo=example1
@@ -304,10 +217,15 @@ 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
POST / HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: ...
Host: example.com
Action=QueryLists
&Version=2020-07-02
&ListArg.member.1=foo
@@ -322,7 +240,6 @@ The ``x-www-form-urlencoded`` serialization is:
&Hi.1=A
&Hi.2=B
Maps
====

@@ -365,10 +282,15 @@ 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
POST / HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Content-Length: ...
Host: example.com
Action=QueryMaps
&Version=2020-07-02
&MapArg.entry.1.key=bar
@@ -393,18 +315,28 @@ Response serialization
The ``awsQuery`` 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
contents of the successful response.
contents of the successful response. A nested element named "ResponseMetadata"
contains a nested element named "RequestId" that contains a unique identifier
for the associated request.

The value of the ``uri`` member of the :ref:`xmlNamespace trait <xmlNamespace-trait>`
is serialized in an ``xmlns`` attribute on the response's XML root node. The
following is a sample response to an operation named ``XmlTest``.

.. code-block:: xml
HTTP/1.1 200 OK
Date: Mon, 27 Jul 2009 12:28:53 GMT
Content-Type: text/xml
Content-Length: ...
<XmlTestResponse xmlns="https://example.com/">
<XmlTestResult>
<testValue>Hello!</testValue>
</XmlTestResult>
<ResponseMetadata>
<RequestId>c6104cbe-af31-11e0-8154-cbc7ccf896c7</RequestId>
</ResponseMetadata>
</XmlTestResponse>
XML shape serialization
@@ -424,11 +356,13 @@ root node named ``ErrorResponse``. A nested element, named ``Error``, contains
the serialized error structure members. :ref:`The HTTP response code is a
resolved value. <awsQuery-error-response-code>`

Serialized error shapes MUST also contain an additional child element ``Code``
that contains the :ref:`resolved error code value <awsQuery-error-code>`. This
is used to distinguish which specific error is serialized in the response.

.. code-block:: xml
:caption: AWS Query error example
HTTP/1.1 400 Bad Request
Date: Mon, 27 Jul 2009 12:28:53 GMT
Content-Type: text/xml
Content-Length: ...
<ErrorResponse>
<Error>
@@ -437,23 +371,38 @@ is used to distinguish which specific error is serialized in the response.
<Message>Hi</Message>
<AnotherSetting>setting</AnotherSetting>
</Error>
<RequestId>foo-id</RequestId>
<RequestId>c6104cbe-af31-11e0-8154-cbc7ccf896c7</RequestId>
</ErrorResponse>
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 :ref:`resolved error code value <awsQuery-error-code>`
that is used to distinguish which specific error is serialized in
the response.
* ``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.


.. _awsQuery-error-response-code:

Error HTTP response code resolution
-----------------------------------
Error HTTP response status code resolution
------------------------------------------

The value of the HTTP response code for the error is resolved using the
following process:
The status code of an error is ``400``, ``500``, or a custom status code
defined by the :ref:`aws.protocols#awsQueryError-trait`. The status code
is determined through the following process:

1. Use the value of the ``httpResponseCode`` member of the :ref:`aws.protocols#awsQueryError-trait`
applied to the error structure, if present.
2. Use the value ``400`` if the value of the :ref:`error-trait` is ``"client"``.
3. Use the value ``500``.


.. _awsQuery-error-code:

Error "Code" resolution
@@ -466,6 +415,141 @@ following process:
applied to the error structure, if present.
2. The :token:`shape name <identifier>` of the error's :ref:`shape-id`.


.. _aws.protocols#awsQuery-trait:

--------------------------------
``aws.protocols#awsQuery`` trait
--------------------------------

Summary
Adds support for the awsQuery protocol to a service. The service MUST have
an :ref:`xmlnamespace-trait`.
Trait selector
``service [trait|xmlNamespace]``

*Service shapes with the xmlNamespace trait*
Value type
Annotation trait.
See
`Protocol tests <https://github.com/awslabs/smithy/tree/__smithy_version__/smithy-aws-protocol-tests/model/awsQuery>`_

.. tabs::

.. code-tab:: smithy

namespace smithy.example

use aws.protocols#awsQuery

@awsQuery
@xmlNamespace(uri: "http://foo.com")
service MyService {
version: "2020-02-05"
}

.. code-tab:: json

{
"smithy": "1.0",
"shapes": {
"smithy.example#MyService": {
"type": "service",
"version": "2020-02-05",
"traits": {
"aws.protocols#awsQuery": {},
"smithy.api#xmlNamespace": {
"uri": "example.com"
}
}
}
}
}

.. _aws.protocols#awsQueryError-trait:

-------------------------------------
``aws.protocols#awsQueryError`` trait
-------------------------------------

Summary
Provides a :ref:`custom "Code" value <awsQuery-error-code>` for
``awsQuery`` errors and an :ref:`HTTP response code <awsQuery-error-response-code>`.
The "Code" of an ``awsQuery`` error is used by clients to determine which
type of error was encountered.
Trait selector
``structure [trait|error]``

The ``httpError`` trait can only be applied to :ref:`structure <structure>`
shapes that also have the :ref:`error-trait`.
Value type
``structure`` that supports the following members:

.. list-table::
:header-rows: 1
:widths: 10 25 65

* - Property
- Type
- Description
* - code
- ``string``
- **Required** The value used to distinguish this error shape during
client deserialization.
* - httpResponseCode
- ``integer``
- **Required** The HTTP response code used on a response that contains
this error shape.

.. important::

The ``aws.protocols#awsQueryError`` trait is only used when serializing
operation errors using the ``aws.protocols#query`` protocol. Unless
explicitly stated in other Smithy protocol specification, this trait has
no impact on other Smithy protocols.

The following example defines an error that uses a custom "Code" of
"InvalidThing" and an HTTP status code of 400.

.. tabs::

.. code-tab:: smithy

use aws.protocols#awsQueryError

@awsQueryError(
code: "InvalidThing",
httpResponseCode: 400,
)
@error("client")
structure InvalidThingException {
message: String
}

.. code-tab:: json

{
"smithy": "1.0",
"shapes": {
"smithy.example#InvalidThingException": {
"type": "structure",
"members": {
"message": {
"target": "smithy.api#String"
}
},
"traits": {
"aws.protocols#awsQueryError": {
"code": "InvalidThing",
"httpResponseCode": 400
},
"smithy.api#error": "client"
}
}
}
}


.. _awsQuery-compliance-tests:

-------------------------
@@ -477,6 +561,3 @@ reference: https://github.com/awslabs/smithy/tree/main/smithy-aws-protocol-tests

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.*

42 changes: 9 additions & 33 deletions docs/source/1.0/spec/aws/aws-query-serialization.rst.template
View file
Original file line number Diff line number Diff line change
@@ -1,40 +1,15 @@
-----------------
Protocol Behavior
-----------------

Every request for the |quoted shape name| protocol MUST be sent to the
root URL (``/``) using the HTTP "POST" method.

The |quoted shape name| protocol does not support custom HTTP bindings.
:ref:`HTTP binding traits <http-traits>` MUST be ignored if they are present.

The |quoted shape name| protocol uses the following headers:

.. list-table::
:header-rows: 1
:widths: 20 20 80

* - Header
- Required
- Description
* - ``Content-Type``
- true
- This header uses the static values of ``application/x-www-form-urlencoded``
for requests and ``text/xml`` for responses.
* - ``Content-Length``
- true
- The standard ``Content-Length`` header defined by
`RFC 7230 Section 3.3.2`_.


---------------------
Request serialization
---------------------

The |quoted shape name| protocol serializes inputs in ``x-www-form-urlencoded``
request bodies. All keys and values MUST be encoded according to :rfc:`3986`.
Requests MUST have the following key value pairs added to the inputs in the
serialized body:
Requests SHALL be sent to the root URL (``/``). Requests SHALL use a POST
request and a body that contains input parameters serialized with a
Content-Type of ``application/x-www-form-urlencoded``. All keys and
values MUST be encoded according to :rfc:`3986`. Requests SHALL contain
a Content-Length header; this protocol does not support chunked
Transfer-Encoding.

Requests MUST include the following key value pairs in the serialized body:

.. list-table::
:header-rows: 1
@@ -54,6 +29,7 @@ concatenated with the following rules:
* "=" is used to separate member keys from values.
* "." is used to separate member name segments within keys.


x-www-form-urlencoded shape serialization
-----------------------------------------

18 changes: 15 additions & 3 deletions docs/source/1.0/spec/aws/aws-restxml-protocol.rst
View file
Original file line number Diff line number Diff line change
@@ -251,9 +251,9 @@ as defined in the ``aws.protocols#restXml`` protocol.

.. _restXml-errors:

-----------------------------
Operation error serialization
-----------------------------
----------------------------
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``,
@@ -290,6 +290,18 @@ using this additional nested XML element as the root node.
<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 :token:`shape name <identifier>` of the error's
:ref:`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