Draft: draft-trammell-taps-interface

Commentary: Appendix B of the API draft provides a sample concrete definition of the API , written in Go . Having concrete examples of the API is clearly useful , but I question whether this draft is the right place for them , since we do n't want to bless a particular API variant . Suggest this appendix be moved to either the implementation draft , or a separate example API implementation draft . 
 The intention here is to show that the API is reasonably expressible and expressive in at least one modern language . I 'd be more than happy to replace it with links to the code and documentation for now though . ( Eventually , examples would be more useful than the sketch though . ) 
 makes sense . 
 Looks good to me . Looks good to me
Paragraph (version A):
In the following sections, we describe the details of application
interaction with Objects through Actions and Events in each phase of
a connection, following the phases described in TAPS-ARCH.  An
example interface sketch in Go is shown in appendix-api-sketch.
Paragraph (version B):
In the following sections, we describe the details of application
interaction with Objects through Actions and Events in each phase of
a connection, following the phases described in TAPS-ARCH.
Paragraph (version A):
Note that most properties are only considered for connection
establishment and can not be changed later on. appendix-specify-
query-params gives an overview of what Transport Parameters can be
specified and queried during which phase.
Paragraph (version B):
Note that most properties are only considered for connection
establishment and can not be changed after a connection is
established; however, they can be queried.  See introspection.
Paragraph (version A):
The Send Parameters are organized in _Message Properties_ and
_Application Intents_.  The Send Parameters share a single namespace
with the Transport Parameters (see transport-params).  This allows to
specify Protocol Properties and that can be overridden on a per-
Message basis or Application Intents that apply to a specific
Message.  See appendix-specify-query-params for an overview.
Paragraph (version B):
The Send Parameters are organized in _Message Properties_ and
_Application Intents_.  The Send Parameters share a single namespace
with the Transport Parameters (see transport-params).  This allows to
specify Protocol Properties and that can be overridden on a per-
Message basis or Application Intents that apply to a specific
Message.
Paragraph (version A):
Transport Features of the protocols that were selected, once the
Connection has been established.  These features correspond to the
properties given in transport-params and can only be queried.
Paragraph (version A):
Protocol Properties of the Protocol Stack in use (see protocol-
props below).  These can be set or queried.  Certain specific
procotol queries may be read-only, on a protocol and property
specific basis.
Paragraph (version B):
Transport Features of the protocol stacks that were selected and
instantiated, once the Connection has been established.  These
features correspond to the properties given in transport-params
and can only be queried.  Instead of preference levels, these
features have boolean values indicating whether or not they were
selected.  Note that these transport features may not fully
reflect the specified parameters given in the pre-establishment
phase.  For example, a certain Protocol Selection Property that an
application specified as Preferred may not actually be present in
the chosen Protocol Stack Instances because none of the currently
available transport protocols had this feature.
Paragraph (version B):
Protocol Properties of the Protocol Stack in use (see protocol-
props below).  These can be set or queried.  Certain specific
procotol queries may be read-only, on a protocol- and property-
specific basis.
Paragraph (version A):
appendix-specify-query-params gives a more detailed overview of the
different types of properties that can be set and queried at
different times.