Document awsQuery protocol #700
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
kstich
commented
Feb 2, 2021
| @@ -538,7 +538,7 @@ table.hlist { | |||
|
|
|||
| code { | |||
| font-size: 90%; | |||
| background-color: #f2f2f2; | |||
| background-color: #e9e9e9; | |||
There was a problem hiding this comment.
Slightly darker to be visible in dark background table rows without being obnoxious in light backgrounds.
kstich
force-pushed
the
query_protocol_docs
branch
from
539d9f2
to
0adcb0e
Compare
JordonPhillips
requested changes
Feb 2, 2021
| * - Key | ||
| - Value | ||
| * - ``Action`` | ||
| - The name of the operation. |
There was a problem hiding this comment.
Specifically the operation's shape name ( :token:`shape name ` )
Comment on lines
150
to
152
| * "&" is used to separate parameter key-value pairs. | ||
| * "=" is used to separate parameter names from values. | ||
| * "." is used to separate nested parameter name segments. |
There was a problem hiding this comment.
parameter -> member ?
Comment on lines
207
to
234
| * - ``list`` | ||
| - Each value provided in the list is serialized as a separate key with | ||
| a "." separator, ``member``, a "." separator, and a ``1`` indexed | ||
| incrementing counter appended to the container's key. The :ref:`xmlName-trait` | ||
| can be used to serialize a property using a custom name instead of | ||
| ``member``. The :ref:`xmlFlattened-trait` can be used to unwrap the | ||
| values into a containing structure or union, with the key not | ||
| containing the initial "." separator and ``member`` segment. | ||
| * - ``set`` | ||
| - A set is serialized identically as a ``list`` shape, but only contains | ||
| unique values. | ||
| * - ``map`` | ||
| - Each key and value in each pair provided in the map is serialized as a | ||
| separate key with a "." separator, ``entry``, a "." separator, a ``1`` | ||
| indexed incrementing counter, a "." separator, and a ``key`` or | ||
| ``value`` segment appended to the container's key. The :ref:`xmlName-trait` | ||
| can be used to serialize a property using custom names instead of | ||
| ``member``, ``key``, or ``value``. The :ref:`xmlFlattened-trait` can be | ||
| used to unwrap the values into a containing structure or union, with | ||
| the key not containing the initial "." separator and ``entry`` segment. | ||
| * - ``structure`` | ||
| - Each member value provided for the structure is serialized as a | ||
| separate key with a "." separator and the member name appended to the | ||
| container's key. The :ref:`xmlName-trait` can be used to serialize a | ||
| property using a custom name. | ||
| * - ``union`` | ||
| - A union is serialized identically as a ``structure`` shape, but only a | ||
| single member can be set to a non-null value. |
There was a problem hiding this comment.
These could use inlined examples
| - Request entity | ||
| * - ``list`` | ||
| - Each value provided in the list is serialized as a separate key with | ||
| a "." separator, ``member``, a "." separator, and a ``1`` indexed |
There was a problem hiding this comment.
specifically the string member. The mixing of quotes and ticks is a bit odd here. The same applies the the other entries
Comment on lines
210
to
212
| incrementing counter appended to the container's key. The :ref:`xmlName-trait` | ||
| can be used to serialize a property using a custom name instead of | ||
| ``member``. The :ref:`xmlFlattened-trait` can be used to unwrap the |
There was a problem hiding this comment.
To what are the traits applied
ditto for member and structure
| property using a custom name. | ||
| * - ``union`` | ||
| - A union is serialized identically as a ``structure`` shape, but only a | ||
| single member can be set to a non-null value. |
There was a problem hiding this comment.
Please define how one serializes a null value. Also empty string
| :ref:`timestampFormat <timestampFormat-trait>` MAY be used to | ||
| customize timestamp serialization. | ||
| * - ``document`` | ||
| - Undefined. Document shapes are not recommended for use in XML based |
There was a problem hiding this comment.
The wording in the request section is better as it calls out that this protocol specifically doesn't support it
Comment on lines
304
to
332
| * - ``list`` | ||
| - XML element. Each value provided in the list is serialized as a nested | ||
| XML element with the name ``member``. The :ref:`xmlName-trait` can be | ||
| used to serialize a property using a custom name. The | ||
| :ref:`xmlFlattened-trait` can be used to unwrap the values into a | ||
| containing structure or union, with the value XML element using the | ||
| structure or union member name. | ||
| * - ``set`` | ||
| - XML element. A set is serialized identically as a ``list`` shape, | ||
| but only contains unique values. | ||
| * - ``map`` | ||
| - XML element. Each key-value pair provided in the map is serialized in | ||
| a nested XML element with the name ``entry`` that contains nested | ||
| elements ``key`` and ``value`` for the pair. The :ref:`xmlName-trait` | ||
| can be used to serialize key or value properties using a custom name, | ||
| it cannot be used to influence the ``entry`` name. The | ||
| :ref:`xmlFlattened-trait` can be used to unwrap the entries into a | ||
| containing structure or union, with the entry XML element using the | ||
| structure or union member name. | ||
| * - ``structure`` | ||
| - XML element. Each member value provided for the structure is | ||
| serialized as a nested XML element where the element name is the | ||
| same as the member name. The :ref:`xmlName-trait` can be used to | ||
| serialize a property using a custom name. The :ref:`xmlAttribute-trait` | ||
| can be used to serialize a property in an attribute of the containing | ||
| element. | ||
| * - ``union`` | ||
| - XML element. A union is serialized identically as a ``structure`` | ||
| shape, but only a single member can be set to a non-null value. |
There was a problem hiding this comment.
These could also use inline examples, or links to the specific sections of the serializing xml shapes page
This fleshes out the documentation for the `awsQuery` protocol.
kstich
force-pushed
the
query_protocol_docs
branch
4 times, most recently
from
0359a7b
to
acc2c04
Compare
JordonPhillips
requested changes
Feb 3, 2021
Comment on lines
142
to
144
| 1. Use the value of the ``ec2QueryName`` trait applied to the member, if | ||
| present. | ||
| 2. Use the value of the ``xmlName`` trait applied to the member with the first |
There was a problem hiding this comment.
These traits should be ref'd
| ----------------------------- | ||
|
|
||
| Error responses in the ``ec2Query`` protocol are wrapped within an XML root | ||
| node named ``ErrorS``. A nested element, named ``Error``, contains the |
There was a problem hiding this comment.
The s in errors should be lowercased
Comment on lines
+148
to
+165
| .. list-table:: | ||
| :header-rows: 1 | ||
| :widths: 50 50 | ||
|
|
||
| * - 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 <shape_id_member>` | ||
| * - ``union`` member | ||
| - The :token:`member name <shape_id_member>` |
There was a problem hiding this comment.
This should show up in normal query too
This adds documentation for ec2Query by abstracting out the docs for awsQuery and including substitutions for the differences. Examples for awsQuery have been added as well.
kstich
force-pushed
the
query_protocol_docs
branch
from
acc2c04
to
1f28d6f
Compare
JordonPhillips
approved these changes
Feb 3, 2021
Merged
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This fleshes out the documentation for the
awsQueryprotocol.By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.