From 30f136b85e1796541c82412ca5fba240683eaaf3 Mon Sep 17 00:00:00 2001 From: Adam Thomas Date: Fri, 4 Feb 2022 11:10:10 -0800 Subject: [PATCH] Add docs for deserialization of ambiguous query params Existing implementations of restJson1 have diverging behavior for query parameters with multiple values depending on whether @httpQuery or @httpQueryParams is used. This updates the docs to use SHOULD to describe the preferred, but not mandatory, behavior. Fixes https://github.com/awslabs/smithy/issues/1071 --- docs/source/1.0/spec/core/http-traits.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/source/1.0/spec/core/http-traits.rst b/docs/source/1.0/spec/core/http-traits.rst index 86cc0e26d6d..966656798e3 100644 --- a/docs/source/1.0/spec/core/http-traits.rst +++ b/docs/source/1.0/spec/core/http-traits.rst @@ -924,6 +924,10 @@ request: 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``. +* When deserializing, server implementations SHOULD use the first encountered + value in the query string for non-collection members. For example, given a + member bound to ``foo`` that targets a string and a query string of + ``foo=a&foo=b``, the deserialized value of ``foo`` should be ``a``. .. important:: Percent-encoding is an implementation detail @@ -1018,6 +1022,12 @@ target map will be serialized in the request query string. Key-value pairs in th are treated like they were explicitly bound using the :ref:`httpQuery-trait`, including the requirement that reserved characters MUST be percent-encoded_. +When servers deserialize the query string into a ``map`` of ``string``, they SHOULD take the +first encountered value for each key. Since this rule applies to all future query string +values, and changing from a ``map`` of ``string`` to a ``map`` of ``list`` of ``string`` is +backwards-incompatible, care should be taken to use ``map`` of ``string`` only when it is +certain that multiple values for any query string will never be meaningful for the operation. + If a member with the ``httpQueryParams`` trait and a member with the :ref:`httpQuery-trait` conflict, clients MUST use the value set by the member with the :ref:`httpQuery-trait` and disregard the value set by ``httpQueryParams``. For example, given the following model: