Asyncronous API callbacks

[RobPhippen]

This issue description is work in progress This is one of three items agreed to be split out from #716 (see this note).

Summary

This issue covers a syntax to enable asynchronous callbacks to be specified.

[fehguy]

Some feedback on this.

Conceptually:
I don't know that this makes sense. To me, there are differences between async responses and callbacks. An async response will be sent, in-band, after a connection is negotiated with the server. An example would be a websocket or an HTTP-long poll. The "trigger" for the response is typically very specific to HTTP connection types, such as interrupting the connection stream, negotiating a 101, etc.

On the other hand, a callback is more of what a webhook would perform--that is, posting directly to a URL, as specified by the caller. While it is async, the connection is broken between negotiation and processing.

This proposal doesn't really cover either of those two. If we're looking to define an async response, we'll have to make it clear how the connection is negotiated and what the trigger would be, if any (it could simply be a socket, but that's outside raw HTTP 1.1). If we're looking to define a callback, we need to make the callback URL part of the request. I guess that's what #735 is for, but it doesn't seem like they're related correctly

Structurally:

• On the x-async-responses: A formal support means no extension (x-). I suggest asyncResponses
• Use a hash instead of array for items in the asyncResponses
• The value for the items in the asyncResponses is essentially an operation, it should simply adhere to that schema
• discriminator doesn't make sense to me. If the payload is what varies, then we should use the standard payload mechanism for determining what type of object is being sent back

[darrelmiller]

There is also other precedents for the use of the term async in HTTP. The prefer header uses the respond-async to describe an interaction that returns a 202 and the client must make a second request to get the results.
It would probably be wise not to introduce more ambiguity in what async means for HTTP.

[fehguy]

Closing as #763 has been merged.