[asterisk-dev] Updated API wiki page

[David M. Lee]

On Dec 4, 2012, at 5:03 PM, Tim Ringenbach wrote:

> So, how will the API accomplish things like logging an agent into a queue, or redirecting to voicemail, or more exotic things like running an Echo test, or playing a telezapper tone? Or asked another way, which use cases aren't in scope of this API?

Playing a telezapper tone should be just playing a sound file, which the API will definitely be able to do.

Since app_echo is easy enough to use from the dialplan, it's not near the top of my list for the API to do. But it probably makes sense just in terms of completeness.

For the rest of what you mentioned, it will probably just ship the channel back out to the dialplan.

In general, I'd like to keep the initial scope of the API to the fundamentals needed for building applications, instead of API's for the existing apps. So things related to app_queue or app_voicemail are out of scope. But you should be able to build your own queue or voicemail app using the API.

> One frustation I've had in the past, is realizing whatever it is I'm trying to do, I need to use another interface to accomplish it. Most commonly, I'm writing an AGI script, and find myself needing to do something only the AMI can do. But I've seen other odd combinations too, e.g. I've seen people resort to using System(asterisk -rx 'some command') from the dialplan.
> 
> But it sounds like you're going to be exposing the Stasis-core API to the manager, so at least I should never have to connect to both the AMI and Stasis to do something.

Until (unless?) the RESTful API (or some other API) matures into the one API to rule them all, you'll have that problem. Asterisk will continue to have separate API's for separate purposes. With stasis-core, we should be able to bring some sanity and consistency across the API's, so that the same function can be exposed via different API's in similar ways, and execute in a similar manner.

It's certainly possible that stasis-http can grow to cover anything you'd want to do. HTTP is the sort of hammer that can turn almost anything into a nail. But for now, I want to keep it focused, and be intentional about what it does and why it does it: a simple interface for building telephony applications.

In practice, there may always be differences between the APIs. If for nothing else, things in stasis-core probably won't be magically exposed to all API's, at least in any sane and reasonable way. If you think in terms of MVC, stasis-core is the model, you still have view and controller code to wire that up to a particular API.

We can be diligent, but at some point someone will add a command to the CLI for debugging, and someone else will find a use case that no one expected for getting at that info from an application.

For the times where there are gaps, you can still get to everything you need via HTTP. It can be ugly, since it breaks from the nicely structured RESTful API. You can access AMI over HTTP[1], AGI over AMI using AsyncAGI[2], and the command line over AMI[3]. As stasis-http matures, the need for this sort of hackery goes to zero. But it's there if you need it.

 [1]: https://wiki.asterisk.org/wiki/x/aIFJ
 [2]: http://ofps.oreilly.com/titles/9780596517342/AGI.html#AGI_id273035
 [3]: https://wiki.asterisk.org/wiki/x/oQg0AQ

>> I'm happy there is is finally going to be a UUID that track the channel that won't have the problem that the current uniqueids have with masquerades. But I do kind of wonder why a third channel identifier is being added, as opposed to fixing one of the two existing ones. (Maybe append the uuid to the channel name?) But maybe that was discussed at AstriDevCon.
> 
> Yeah; my intention is to fix what's there rather than add a ReallyUniqueID field. I'm also realizing that it's going to take a bit of software archeology to figure out masquerades, uniqueid, etc. and come up with a plan for how to fix it.
> 
> On the subject of uniqueids and channel masquerades, I can point you to my own email from a few years ago:  http://lists.digium.com/pipermail/asterisk-dev/2010-June/044754.html and an old reviewboard patch https://reviewboard.asterisk.org/r/760/

Thanks! Good history about UniqueID. For those playing along at home, I'm keeping my notes at https://wiki.asterisk.org/wiki/x/IwBRAQ.

You also had a list of use cases from an earlier email:

On Dec 4, 2012, at 1:23 PM, Tim Ringenbach wrote:
>  - Redirect/transfer channels to difference places in the dialplan

Yes. The stasis application should exit with some sort of 'go back to the dialplan' command.

>  - Pickup a ringing channel

Yes. I am embarrassed that I had not written that down earlier.

>  - Detect a fax tone, turn on recording (maybe you're troubleshooting failed faxes) but without mixing the streams, and redirect to ReceiveFax()

Had not thought of that. That might be better suited for staying in the dialplan, though.

>  - Observe that there's 10 people waiting in a queue for more than 30 minutes, and start logging more people into the queue, or redirecting calls to specific phones

For app_queue, no. But you should be able to write your own queue using the API that does this.

>  - Detect that someone's talking in a Conference and send a signal to a web app

I'll be pedantic and replace Conference with Bridge, and say probably. This would depend on features of Asterisk bridging to enable this.

>  - Light up a BLF on a phone after someone dials a special extension from a speed dial that logs them in to a custom queue implemented using Stasis

Probably. That would depend on BLF support in Asterisk.

>  - Findme/Followme: record a file that will automatically be deleted when the call is over, then call a bunch of numbers, at least one of which is a local phone that's forwarded to a different number, play them an IVR that uses this file, then bridge 0 or 1 of them to the original call, hanging up the others. Bonus: have the CDRs make sense at the end of this.

I was with you up until you said CDR :-P

Breaking it down:
 * record a file - sure
 * that will automatically be deleted when the call is over - automatic, no. But the application can explicitly delete the file when it wants
 * then call a bunch of numbers - sure
 * at least one of which is a local phone that's forwarded to a different number - that's more in the dialplan than the API
 * play them an IVR that uses this file - sure
 * then bridge 0 or 1 of them to the original call - sure
 * hanging up the others - sure

-- 
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/20121206/9175479e/attachment-0001.htm>