Change:
Address issue Add more intro section, with friendly diagrams Highlight why we use events, messages, and racing
To me the document is in very good shape, but there are several things that just appear, and a few short paras and maybe a simple picture could help avoid people giving-up before they know the document is useful to them. We seem to not introduce it nicely, I'd suggest: This isn't scarey (draw a simple familiar figure to start our story, that the reader immediately recognises) Sockets v Streams ... we speak of messages, let's explain early that they ae all you need for any app. Events ... we know these are "nromal" - but let's say we provide an eevent-driven interface. it would even be worth saying why thsi is much better (Tommy - Apple have been doing this from the start, can you perhaps say why it is beautiful?) Comments follow: Section: Background. The last part of this section suddenly introduces messages. I know it is just an example, but readers may be already looking here at whether this is an interface to TCP or UDP or something else ... and I think we do not really tackle that earlier enough. One way to help that would be to draw a diagram that looks something like this, in this section: +-----------------------------------------------------+ +------------------------+----------------------------+ | +------------------------|----------------------------+ +------------------------|----------------------------+ | +------------------------|----------------------------+ +------------------------|----------------------------+ +------------------------|----------------------------+ +-----------------------------------------------------+ And the say that the Transport Services API provides message-oriented communication using transport protocols (e.g. UDP, TCP, etc). I'd also mention the words /data transfer/ somewhere. Providing a simpler earlier diagram may also be slightly easier on the new reader. In the same way, the intro should explain a little of the idea of /events/ - common enough to some, but may be unexpected for a new reader.
I suspect you're already writing this sort of approach: I think it would be super nice if the background/intro text clearly had a para expalining that this is a call-back based API. I do suspect that many people coming to this will be atrracted because the new API is simple and provides a more modern interface. The rationale for why we design it to enable multiple transports, etc, is the "detail inside the engine" the fact it delivers what they want is the first point to make:-).
NAME does close this issue?
NAME Yes, I think so.
lgtm modulo NAME commentsLGTM!

Discussion:
Transport Services API I-D.ietf-taps-interface and Implementation I- D.ietf-taps-impl documents. <ins> 1.1. The model for using sockets for networking can be represented as follows: applications create connections and transfer data using the socket API, which provides the interface to the implementations of UDP and TCP (typically implemented in the system's kernel), which in turn send data over the available network layer interfaces. The Transport Services architecture maintains this general model of interaction, but aims to both modernize the API surface exposed for transport protocols and enrich the capabilities of the transport system implementation. The Transport Services API I-D.ietf-taps-interface defines the mechanism for an application to create and monitor network connections, and transfer data.  The Implementation I-D.ietf-taps- impl is responsible for mapping the API into the various available transport protocols and managing the available network interfaces and paths. There are a few key departures that Transport Services makes from the sockets API: it presents an asynchronous, event-driven API; it uses messages for respresenting data transfer to applications; and it assumes an implementation that can use multiple IP addresses, multiple protocols, multiple paths, and provide multiple application streams. 1.2. Originally, sockets presented a blocking interface for establishing connections and transferring data.  However, most modern applications interact with the network asynchronously.  When sockets are presented as an asynchronous interface, they generally use a try-and-fail model.  If the application wants to read, but data has not yet been received from the peer, the call to read will fail.  The application then waits for a notification that it should try again. All interaction with a Transport Services system is expected to be asynchronous, and use an event-driven model unlike sockets events. For example, if the application wants to read, its call to read will not fail, but will deliver an event containing the received data once it is available. The Transport Services API also delivers events regarding the lifetime of a connection and changes to available network links, which were not previously made explicit in sockets. Using asynchronous events allows for a much simpler interaction model when establishing connections and transferring data.  Events in time more closely reflect the nature of interactions over networks, as opposed to how sockets represent network resources as file system objects that may be temporarily unavailable. 1.3. Sockets provide a message interface for datagram protocols like UDP, but provide an unstructured stream abstraction for TCP.  While TCP does indeed provide the ability to send and receive data as streams, most applications need to interpret structure within these streams. HTTP/1.1 uses character delimiters to segment messages over a stream; TLS record headers carry a version, content type, and length; and HTTP/2 uses frames to segment its headers and bodies. In order to more closely match the way applications use the network, the Transport Services API respresents data as messages.  Messages seamlessly work with transport protocols that support datagrams or records, but can also be used over a stream by defining the application-layer framing being used framing. 1.4. Sockets, for protocols like TCP, are generally limited to connecting to a single address over a single interface.  They also present a single stream to the application.  Software layers built upon sockets often propagate this limitation of a single-address single-stream model.  The Transport Services architecture is designed to handle multiple candidate endpoints, protocols, and paths; and support multipath and multistreaming protocols. Transport Services implementations are meant to be flexible at connection establishment time, considering many different options and trying to select the most optimal combinations (gathering and racing).  This requires applications to provide higher-level endpoints than IP addresses, such as hostnames and URLs, which are used by a Transport Services implementation for resolution, path selection, and racing. Flexibility after connection establishment is also important. Transport protocols that can migrate between multiple network layer interfaces need to be able to process and react to interface changes. Protocols that support multiple application-layer streams need to support initiating and receiving new streams using existing connections. </ins> 2. The Transport Services architecture is based on the survey of