<html><head></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><br><div><div>On Dec 1, 2012, at 5:40 AM, Dan Jenkins wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"><span class="Apple-style-span" style="border-collapse: separate; font-family: Helvetica; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; font-size: medium; ">Hi All, <div><br></div><div>Thought I'd put some comments against parts of the wiki,</div><div><br></div><div><i><span style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; font-size: 13px; line-height: 17.33333396911621px; ">We're going to start with fixing one of the most glaring problems with the current APIs: </span><a href="https://issues.asterisk.org/jira/browse/ASTERISK-20725" rel="nofollow" target="_blank" style="color: rgb(0, 109, 175); text-decoration: initial; outline-style: none; outline-width: initial; outline-color: initial; font-family: Arial, Helvetica, FreeSans, sans-serif; font-size: 13px; line-height: 17.33333396911621px; ">add a stable identifier to channels</a><span style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; font-size: 13px; line-height: 17.33333396911621px; ">, and use that identifier consistently throughout AMI. This solves a big problem for current AMI+AGI based applications.</span><b> - </b></i><span style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; font-size: 13px; line-height: 17.33333396911621px; "><b>LOVE this!</b></span></div></span></blockquote><div><br></div><div>As will EVERYONE!</div><br><blockquote type="cite"><span class="Apple-style-span" style="border-collapse: separate; font-family: Helvetica; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; font-size: medium; "><div><span style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; font-size: 13px; line-height: 17.33333396911621px; "><i>Unfortunately, solving some of the larger problems would be very intrusive with the current API's, and introduce a host of breaking changes. Some are so fundamental, we would essentially be rewriting the interface. That's not acceptable; the current API's aren't going anywhere anytime soon.<span class="Apple-converted-space"> </span></i>-<span class="Apple-converted-space"> </span><b>Is there not scope to enhance these APIs? There was discussion a few weeks back on this mailing list about enhancing the AMI to support JSON/XML rather than key value return separated strings (After reading further down there is a line saying "</b></span><i><span style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; font-size: 13px; line-height: 17.33333396911621px; ">AMI Event Structure</span><span style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; font-size: 13px; line-height: 17.33333396911621px; "> - AMI events should be generated into a key/value object pair instead of the </span><tt style="color: rgb(51, 51, 51); font-size: 13px; line-height: 17.33333396911621px; ">printf</tt><span style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; font-size: 13px; line-height: 17.33333396911621px; ">-style string formatting currently used. This would allow Stasis to reuse the existing events.</span></i><b style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; font-size: 13px; line-height: 17.33333396911621px; ">" - Does this mean that the suggestion above needs to happen anyway?)</b></div></span></blockquote><div><br></div><div>There will be some improvements to AMI. Both externally visible (the stable id thing) and internal to the implementation (getting rid of the printf-style event generation). But some of the bigger things simply make better sense for a new API, instead of upheaving AMI.</div><div><br></div><div>Take JSON/XML for example. The two big advantages of either would be 1) availability of parsers and 2) ability to use structured data. The current format is so easy to parse, #1 isn't much of a win at all. #2 is difficult, because the structured data cannot be represented in the existing format. So you can limit yourself to data that can be represented in the AMI format (takes away advantage #2), or improve the AMI format to represent structured data (which would be a huge breaking change).</div><div><br></div><div>So my preference is to leave AMI fundamentally the way it is. The new RESTful API will speak JSON (and probably XML), taking full advantage of having structured data, without the legacy of an old key: value protocol holding it back.</div><br><blockquote type="cite"><span style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; font-size: 13px; line-height: 17.33333396911621px; "> <i>The </i></span><tt style="color: rgb(51, 51, 51); font-size: 13px; line-height: 17.33333396911621px; "><i>stasis-http</i></tt><span style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; font-size: 13px; line-height: 17.33333396911621px; "><i> component will be built upon this message bus to expose a RESTful API, also utilizing WebSockets for asynchronous communication to the external applications.</i> - <b>Can you go into a bit more detail about why this API would use Websockets? What kinds of scenarios do you see someone interacting with Asterisk directly with Websockets, in an API type of way? </b></span></blockquote><div><br></div><div>The WebSocket interface is for asynchronous event notification from Asterisk bask to the application. For example, when a channel hangs up, it needs to send an event to the application(s) interested in that event. That event would be passed back over the WebSocket. There are other ways of doing this while sticking with HTTP as the protocol (post back to a URI, long polling, etc.). But using WebSockets seems like a great place to start.</div><div><br></div><div><ul class="MailOutline"><li>Asterisk already has WebSocket support implemented (Thanks, file!)</li><li>Using <a href="http://einaros.github.com/ws/">wscat</a>, you can easily use a WebSocket from the command line.</li><li>You can find WebSocket enabled client libraries for the major programming languages.</li></ul></div><div><br></div><blockquote type="cite"><span style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; font-size: 13px; line-height: 17.33333396911621px; "><b>I wouldn't allow a browser to connect directly to Asterisk for example, I would get it going through a middle server that connects to Asterisk and it's sole purpose is to connect to hundreds of clients using web sockets. </b></span></blockquote><div><br></div><div>Absolutely. Even though it's an HTTP based API, I would highly recommend against accessing it directly from a browser in production. Although that might very convenient in test and development :-D</div><div><br></div><div>We'll probably have to put together best practices steering folks toward the better ways of structuring their applications.</div><div><br></div><blockquote type="cite"><span style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; font-size: 13px; line-height: 17.33333396911621px; "><b>I think we have to be careful about wanting to make this new API accessible for everyone but still keep Asterisk doing what it's good at, I hope this makes sense... However, I can also see how connecting with websockets from a server could be useful, but I think I'd rather keep a RESTful interface, where you can tell Asterisk "for an event that you would emit about x you need to send the data to uri y as an HTTP call" and let the data be consumed that way.</b></span></blockquote><div><br></div><div>It's very interesting that you say that. I had a similar debate with someone internally. While I did think about using HTTP callbacks instead of using WebSockets, I didn't really care about that approach for several reasons.</div><div><div><ul><li>HTTP callbacks can cause issues if there are firewalls in the mix. With WebSockets, there's just one server, and one hole to poke in the firewall.</li><li>Using WebSockets keeps a very consistent distinction between who's the client and who's the server. HTTP callback puts a burden on the client to be both.</li><li>HTTP callback is also an authentication burden for the API client. When it gets an HTTP callback, it has to authenticate it to ensure that it really came from Asterisk.</li></ul><div>So none of these are really big issues, but it's enough for me to prefer WebSockets.</div><div><br></div></div></div><blockquote type="cite"><span class="Apple-style-span" style="font-family: Arial, Helvetica, FreeSans, sans-serif; font-size: 13px; line-height: 17px; ">Even so, I love the fact that Stasis is happening - it's the best way to get web developers using such a "toolkit" as it's put - if it's done right it could open the doors to some amazing applications.</span></blockquote><div><br></div>Yes \o/</div><div><br><blockquote type="cite"><font color="#333333" face="Arial, Helvetica, FreeSans, sans-serif"><span style="line-height: 17.33333396911621px; ">In terms of Authentication and </span></font><font color="#333333" face="Arial, Helvetica, FreeSans, sans-serif"><span style="line-height: 17.33333396911621px; ">Authorisation</span></font><font color="#333333" face="Arial, Helvetica, FreeSans, sans-serif"><span style="line-height: 17.33333396911621px; ">, I'd like to see more of an effort behind this, with mechanisms to create tokens to be used rather than user and pass in plain text or even the handshake system currently in Asterisk, this is something that isn't a huge issue right now with Asterisk's current APIs but if we're looking at HTTP first with stasis then we should be thinking about how this would be best used within HTTP and make sure it works for other implementations too.</span></font></blockquote><div><br></div><div>Yes. In general terms of Stasis (thinking of a future where it has multiple protocol bindings), it should support the authentication mechanisms prevalent for its protocol bindings. If we find ourselves inventing a authentication mechanism, we're doing it wrong.</div><div><br></div><div>For HTTP, I actually don't have a problem with using Basic Auth (which would be plain text username/password), so long as it's only done over HTTPS (so the plain text password never goes out on the wire). It's simple, it's secure, and it works everywhere.</div><div><br></div><div>Quite a few RESTful API's seem to use some sort of API key and request signing scheme. If anyone wants stasis-http to support such a scheme, please point out a standard we could implement.</div><div><br></div><blockquote type="cite"><span class="Apple-style-span" style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; line-height: 17px; ">In terms of encryption, shouldn't this be down to the libraries off of stasis? So stasis-http would take care of encryption within it, as different protocols have different forms of encryption which is relevant those those protocols? Is this the plan?</span></blockquote><div><br></div>Yes. Encryption is easy (relatively speaking) for stasis-http, since it will just use the HTTPS support already in main/http.c.</div><div><br><blockquote type="cite"><span class="Apple-style-span" style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; line-height: 17px; ">I also agree with Olle on the granularity of permissions of users within this API, but for a different reason, the AMI has basic granularity in terms of what it's able to do, which is used enormously, why wouldn't you do something similar within this new API system?</span></blockquote><div><br></div><div><div>Others in the thread have covered the problems we've had with AMI's granular permissions.</div><div><br></div></div><div>I think I need to reword that requirement to be more clear. I'm not saying we'll never have any sort of authorization scheme with the new API. What we're getting at is that it's not a requirement for a v1 API, and we have the time to think through the use cases and get the permissions right.</div><div><br></div><div><br></div><blockquote type="cite"><span class="Apple-style-span" style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; line-height: 17px; ">I'm sure we'll have to add to that high level list of summary features, as I'm sure we'll end up thinking of more solutions that would be perfect for this type of interface, I'm interested to see what other tasks other people think could be achieved using such an API</span></blockquote><div><br></div><div>Definitely! I hoping that we can get a good, broad list of summary features. That way we can prioritize the list to decide what we'll go after first, while keeping the lower priority items in mind so we don't code ourselves into a corner.</div><div><br></div><div>So start thinking of what you want to add to the list, everybody!</div><br><blockquote type="cite"><span class="Apple-style-span" style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; line-height: 17px; ">Let me know if I've misinterpreted anything in the wiki,</span></blockquote><div><br></div><div>I think you're largely on the right track. Thanks for the feedback!</div><br><blockquote type="cite"><span class="Apple-style-span" style="color: rgb(51, 51, 51); font-family: Arial, Helvetica, FreeSans, sans-serif; line-height: 17px; ">Dan</span><br class="Apple-interchange-newline"></blockquote></div><br><div>
<span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: Helvetica; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; font-size: medium; "><span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: Helvetica; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; font-size: medium; "><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: Helvetica; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; font-size: medium; "><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><div>-- <br>David M. Lee<br>Digium, Inc. | Software Developer<br>445 Jan Davis Drive NW - Huntsville, AL 35806 - USA<br>Check us out at: <a href="http://www.digium.com/">www.digium.com</a> & <a href="http://www.asterisk.org/">www.asterisk.org</a></div></div></span></div></span></span>
</div>
<br></body></html>