Skip to content

Commit

Permalink
Add documentation for awsJson1_1
Browse files Browse the repository at this point in the history 
This adds documentation for awsJson1_1 by abstracting out the docs
for awsJson1_0 and including substitutions for the small differences.
  • Loading branch information
@JordonPhillips
JordonPhillips committed Feb 1, 2021
1 parent 1afd227 commit 73ed360
Show file tree
Hide file tree
Showing 3 changed files with 214 additions and 213 deletions.
211 changes: 5 additions & 206 deletions docs/source/1.0/spec/aws/aws-json-1_0-protocol.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,209 +56,8 @@ See
}
}


----------------
Supported traits
----------------

The ``awsJson1_0`` protocol supports the following traits
that affect serialization:

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

* - Trait
- Description
* - :ref:`cors <cors-trait>`
- Indicates that the service supports CORS.
* - :ref:`jsonName <jsonName-trait>`
- By default, the JSON property names used in serialized structures are
the same as a structure member name. The ``jsonName`` trait changes
the JSON property name to a custom value.
* - :ref:`timestampFormat <timestampFormat-trait>`
- Defines a custom timestamp serialization format.


------------------
Protocol Behaviors
------------------

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

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

The ``awsJson1_0`` protocol uses the following headers:

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

* - Header
- Required
- Description
* - ``Content-Type``
- true
- This header has a static value of ``application/x-amz-json-1.0``.
* - ``Content-Length``
- true
- The standard ``Content-Length`` header defined by
`RFC 7230 Section 3.3.2`_.
* - ``X-Amz-Target``
- true for requests
- The value of this header is the :token:`shape name <identifier>` of the
service's :ref:`shape-id` joined to the
:token:`shape name <identifier>` of the operation's :ref:`shape-id`,
separated by a single period (``.``) character.

For example, the value for the operation ``ns.example#MyOp`` of the
service ``ns.example#MyService`` is ``MyService.MyOp``.


-------------------
Shape serialization
-------------------

The ``awsJson1_0`` protocol serializes all shapes into a JSON
document body with no HTTP bindings supported. The following table shows how
to convert each shape type:

.. list-table::
:header-rows: 1
:widths: 25 75

* - Smithy type
- JSON type
* - ``blob``
- JSON ``string`` value that is base64 encoded.
* - ``boolean``
- JSON boolean
* - ``byte``
- JSON number
* - ``short``
- JSON number
* - ``integer``
- JSON number
* - ``long``
- JSON number
* - ``float``
- JSON number
* - ``double``
- JSON number
* - ``bigDecimal``
- JSON number. Unfortunately, this protocol serializes bigDecimal
shapes as a normal JSON number. Many JSON parsers will either
truncate the value or be unable to parse numbers that exceed the
size of a double.
* - ``bigInteger``
- JSON number. Unfortunately, this protocol serializes bigInteger
shapes as a normal JSON number. Many JSON parsers will either
truncate the value or be unable to parse numbers that exceed the
size of a double.
* - ``string``
- JSON string
* - ``timestamp``
- JSON number (default). This protocol uses ``epoch-seconds``, also
known as Unix timestamps, in JSON payloads represented as a double.
However, the :ref:`timestampFormat <timestampFormat-trait>` MAY be
used to customize timestamp serialization.
* - ``document``
- Any JSON value
* - ``list``
- JSON array
* - ``set``
- JSON array. A set is serialized identically as a ``list`` shape,
but only contains unique values.
* - ``map``
- JSON object
* - ``structure``
- JSON object. Each member value provided for the structure is
serialized as a JSON property where the property name is the same
as the member name. The :ref:`jsonName-trait` can be used to serialize
a property using a custom name. A null value MAY be provided or
omitted for a :ref:`boxed <box-trait>` member with no observable
difference.
* - ``union``
- JSON object. A union is serialized identically as a ``structure``
shape, but only a single member can be set to a non-null value.


~~~~~~~~~~~~~~~~~~~~~~~~
Empty body serialization
~~~~~~~~~~~~~~~~~~~~~~~~

When an operation has no modeled input or if no input parameters are provided,
a client MUST send an empty JSON object (``{}``) as the request body. Server
implementations MUST also accept empty request bodies.

When an operation has no modeled output or no output parameters are provided,
server implementations SHOULD send an empty response body. The server MUST
still send the protocol's ``Content-Type`` header in this case. Clients MUST
also accept an empty JSON object as the response body.


.. awsJson1_0-errors:
-----------------------------
Operation error serialization
-----------------------------

Error responses in the ``awsJson1_0`` protocol are serialized identically to
standard responses with one additional component to distinguish which error
is contained. New server-side protocol implementations SHOULD use a body field
named ``__type``. The component MUST be one of the following: an additional
header with the name ``X-Amzn-Errortype``, a body field with the name ``code``,
or a body field named ``__type``. The value of this component SHOULD contain
the error's :ref:`shape-id`.

Legacy server-side protocol implementations sometimes include different
information in this value. All client-side implementations SHOULD support
sanitizing the value to retrieve the disambiguated error type using the
following steps:

1. If a ``:`` character is present, then take only the contents **before** the
first ``:`` character in the value.
2. If a ``#`` character is present, then take only the contents **after** the
first ``#`` character in the value.

All of the following error values resolve to ``FooError``:

* ``FooError``
* ``FooError:http://internal.amazon.com/coral/com.amazon.coral.validate/``
* ``aws.protocoltests.restjson#FooError``
* ``aws.protocoltests.restjson#FooError:http://internal.amazon.com/coral/com.amazon.coral.validate/``


-----------------------------------------------------
Differences between ``awsJson1_0`` and ``awsJson1_1``
-----------------------------------------------------

There are two difference between ``awsJson1_0`` and
:ref:`aws.protocols#awsJson1_1-trait`. First, the static value of the
``Content-Type`` header is different. In ``awsJson1_0`` it MUST be
``application/x-amz-json-1.0`` and in ``awsJson1_1`` it MUST be
``application/x-amz-json-1.1``.

Second, error type serialization is different. In ``awsJson1_0``, servers SHOULD
send the error shape's full :ref:`shape-id` in the ``__type`` field of the body.
In ``awsJson1_1``, servers SHOULD only send the error's
:token:`shape name <identifier>`. However, clients MUST accept either behavior
for both protocols. See :ref:`awsJson1_0-errors` for full details on how to
deserialize errors for ``awsJson1_0``.


-------------------------
Protocol compliance tests
-------------------------

A full compliance test suite is provided and SHALL be considered a normative
reference: https://github.com/awslabs/smithy/tree/main/smithy-aws-protocol-tests/model/awsJson1_0

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

.. _`RFC 7230 Section 3.3.2`: https://tools.ietf.org/html/rfc7230#section-3.3.2
.. |quoted shape name| replace:: ``awsJson1_0``
.. |protocol content type| replace:: ``application/x-amz-json-1.0``
.. |protocol error type contents| replace:: :ref:`shape-id`
.. |protocol test link| replace:: https://github.com/awslabs/smithy/tree/main/smithy-aws-protocol-tests/model/awsJson1_0
.. include:: aws-json.rst.template
13 changes: 6 additions & 7 deletions docs/source/1.0/spec/aws/aws-json-1_1-protocol.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ This specification defines the ``aws.protocols#awsJson1_1`` protocol.
----------------------------------

Summary
Adds support for an HTTP protocol that sends POST requests and
Adds support for an HTTP protocol that sends "POST" requests and
responses with JSON documents.
Trait selector
``service``
Expand Down Expand Up @@ -56,9 +56,8 @@ See
}
}

.. important::

This protocol only permits the :ref:`httpPayload-trait` to be applied to
members that target structures, documents, strings, blobs, or unions.

*TODO: Add specifications, protocol examples, etc.*
.. |quoted shape name| replace:: ``awsJson1_1``
.. |protocol content type| replace:: ``application/x-amz-json-1.1``
.. |protocol error type contents| replace:: :token:`shape name <identifier>`
.. |protocol test link| replace:: https://github.com/awslabs/smithy/tree/main/smithy-aws-protocol-tests/model/awsJson1_1
.. include:: aws-json.rst.template
Loading

0 comments on commit 73ed360

Please sign in to comment.