Add Wire Protocol Selection guide

These guidelines define how clients and servers should identify protocols
and claim requests. Additional updates are made to each protocol defined
in the specifiction to define the set of characteristics that servers must
use to identify inputs from clients.

Author: kstich

.changes/next-release/documentation-21443c5c01622dc85ab5ae0948a6c7199d1de00d.json

@@ -0,0 +1,7 @@
+{
+  "type": "documentation",
+  "description": "Add Wire Protocol Selection guide",
+  "pull_requests": [
+    "[#2938](https://github.com/smithy-lang/smithy/pull/2938)"
+  ]
+}

docs/source-2.0/additional-specs/protocols/smithy-rpc-v2.rst

@@ -156,6 +156,25 @@ that affect serialization:
         to services.
 
 
+---------------------------
+Identification for claiming
+---------------------------
+
+Services that support this protocol MUST use the following characteristics to
+identify and claim requests:
+
+#. The Smithy-Protocol HTTP request header is set and contains the value
+   ``rpc-v2-cbor``.
+#. The HTTP request method is ``POST``.
+#. The HTTP request path matches the form ``{prefix?}/service/{serviceName}/operation/{operationName}``.
+#. The optional ``{prefix?}`` segment in the HTTP request path matches the
+   service’s runtime path prefix, if configured.
+#. The ``{serviceName}`` segment in the HTTP request path matches the :token:`shape name <smithy:Identifier>`
+   of the service's :ref:`shape-id` in the Smithy model.
+#. The ``{operationName}`` segment in the HTTP request path matches a :token:`shape name <smithy:Identifier>`
+   of an operation bound to the service.
+
+
 ------------------
 Protocol behaviors
 ------------------

docs/source-2.0/aws/protocols/aws-ec2-query-protocol.rst

@@ -171,6 +171,25 @@ that affect serialization:
     This protocol does not support document types.
 
 
+---------------------------
+Identification for claiming
+---------------------------
+
+Services that support this protocol MUST use the following characteristics to
+identify and claim requests:
+
+#. The ``Content-Type`` HTTP request header is set and contains the value
+   ``application/x-www-form-urlencoded``.
+#. The HTTP request method is ``POST``.
+#. The HTTP request path is ``/``.
+#. The :token:`shape name <smithy:Identifier>` of the service's :ref:`shape-id`
+   in the Smithy model is ``AmazonEC2``.
+#. The HTTP request body contains a ``Version`` key with its value set to the
+   :ref:`"version" property of the service <service>`.
+#. The HTTP request body contains an ``Action`` key with a value that matches a
+   :token:`shape name <smithy:Identifier>` of an operation bound to the service.
+
+
 .. |quoted shape name| replace:: ``ec2Query``
 .. |name resolution text| replace:: See :ref:`aws.protocols#ec2QueryName-query-key-naming`
    for how to serialize a property using a custom name

docs/source-2.0/aws/protocols/aws-json.rst.template

@@ -25,6 +25,27 @@ that affect serialization:
         to services.
 
 
+---------------------------
+Identification for claiming
+---------------------------
+
+Services that support this protocol MUST use the following characteristics to
+identify and claim requests:
+
+#. The ``Content-Type`` HTTP request header is set and contains the value
+   |protocol content type|.
+#. The HTTP request method is ``POST``.
+#. The HTTP request path is ``/``.
+#. The ``X-Amz-Target`` HTTP request header is set and contains a value that
+   matches the form ``{serviceName}.{operationName}``.
+#. The ``{serviceName}`` segment in the ``X-Amz-Target`` HTTP request header
+   matches the :token:`shape name <smithy:Identifier>` of the service's
+   :ref:`shape-id` in the Smithy model.
+#. The ``{operationName}`` segment in the ``X-Amz-Target`` HTTP request header
+   matches a :token:`shape name <smithy:Identifier>` of an operation bound to
+   the service.
+
+
 ------------------
 Protocol Behaviors
 ------------------

docs/source-2.0/aws/protocols/aws-query-protocol.rst

@@ -93,6 +93,24 @@ that affect serialization:
       - Indicates that an operation supports compressing requests from clients
         to services.
 
+
+---------------------------
+Identification for claiming
+---------------------------
+
+Services that support this protocol MUST use the following characteristics to
+identify and claim requests:
+
+#. The ``Content-Type`` HTTP request header is set and contains the value
+   ``application/x-www-form-urlencoded``.
+#. The HTTP request method is ``POST``.
+#. The HTTP request path is ``/``.
+#. The HTTP request body contains a ``Version`` key with its value set to the
+   :ref:`"version" property of the service <service>`.
+#. The HTTP request body contains an ``Action`` key with a value that matches a
+   :token:`shape name <smithy:Identifier>` of an operation bound to the service.
+
+
 .. |quoted shape name| replace:: ``awsQuery``
 .. |name resolution text| replace:: The :ref:`xmlName-trait` can be used to serialize a property using a custom name
 .. |query list text| replace::

docs/source-2.0/aws/protocols/aws-restjson1-protocol.rst

@@ -189,6 +189,25 @@ that affect serialization:
         to services.
 
 
+---------------------------
+Identification for claiming
+---------------------------
+
+Services that support this protocol MUST use the following characteristics to
+identify and claim requests:
+
+#. The pair of HTTP request method and HTTP request path matches the defined
+   method and path of an operation bound to the service.
+#. The ``Content-Type`` HTTP request header is set and contains a value that
+   matches :ref:`the operation’s input’s derived Content-Type <restJson1-content-type>`
+   or is allowed to contain a custom ``Content-Type`` via the ``@httpHeader``
+   trait.
+
+   This defaults to ``application/json``.
+
+
+.. _restJson1-content-type:
+
 ------------
 Content-Type
 ------------

docs/source-2.0/aws/protocols/aws-restxml-protocol.rst

@@ -192,6 +192,25 @@ that affect serialization:
     This protocol does not support document types.
 
 
+---------------------------
+Identification for claiming
+---------------------------
+
+Services that support this protocol MUST use the following characteristics to
+identify and claim requests:
+
+#. The pair of HTTP request method and HTTP request path matches the defined
+   method and path of an operation bound to the service.
+#. The ``Content-Type`` HTTP request header is set and contains a value that
+   matches :ref:`the operation’s input’s derived Content-Type <restXml-content-type>`
+   or is allowed to contain a custom ``Content-Type`` via the ``@httpHeader``
+   trait.
+
+   This defaults to ``application/xml``.
+
+
+.. _restXml-content-type:
+
 ------------
 Content-Type
 ------------

docs/source-2.0/guides/index.rst

@@ -12,6 +12,7 @@ Guides
     model-linters
     model-validation-examples
     evolving-models
+    wire-protocol-selection
     style-guide
     model-translations/index
     building-codegen/index