Document API and Implementation Guidance

[benjchristensen]

There are a handful of things in the protocol that benefit from seeing code, or at least pseudo code, to communicate the intent, and guide implementation.

For example:

• DuplexConnection
  • support alternate transports with optional frame length
  • support streamId being provided by transport, or as part of framing
• Request/Response APIs
  • Publisher
  • requestStream etc

I think it best to create a SuggestedAPIs.md doc, or something like that, and link to the appropriate sections from the Protocol.md doc.

[tmontgomery]

A SuggestedAPIs.md doc sounds perfect to me. There are some subtleties that could be much more clarified that way.