[asterisk-dev] Asterisk 12 API improvements

[David M. Lee]

On Dec 1, 2012, at 5:40 AM, Dan Jenkins wrote:

> Hi All, 
> 
> Thought I'd put some comments against parts of the wiki,
> 
> We're going to start with fixing one of the most glaring problems with the current APIs: add a stable identifier to channels, and use that identifier consistently throughout AMI. This solves a big problem for current AMI+AGI based applications. - LOVE this!

As will EVERYONE!

> 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. - 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 "AMI Event Structure - AMI events should be generated into a key/value object pair instead of the printf-style string formatting currently used. This would allow Stasis to reuse the existing events." - Does this mean that the suggestion above needs to happen anyway?)

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.

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).

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.

>  The stasis-http component will be built upon this message bus to expose a RESTful API, also utilizing WebSockets for asynchronous communication to the external applications. - 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?

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.

Asterisk already has WebSocket support implemented (Thanks, file!)
Using wscat, you can easily use a WebSocket from the command line.
You can find WebSocket enabled client libraries for the major programming languages.

> 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.

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

We'll probably have to put together best practices steering folks toward the better ways of structuring their applications.

> 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.

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.
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.
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.
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.
So none of these are really big issues, but it's enough for me to prefer WebSockets.

> 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.

Yes \o/

> In terms of Authentication and Authorisation, 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.

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.

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.

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.

> 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?

Yes. Encryption is easy (relatively speaking) for stasis-http, since it will just use the HTTPS support already in main/http.c.

> 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?

Others in the thread have covered the problems we've had with AMI's granular permissions.

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.


> 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

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.

So start thinking of what you want to add to the list, everybody!

> Let me know if I've misinterpreted anything in the wiki,

I think you're largely on the right track. Thanks for the feedback!

> Dan

-- 
David M. Lee
Digium, Inc. | Software Developer
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at:  www.digium.com  & www.asterisk.org

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20121203/6c0cb04f/attachment.htm>