• If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • Buried in cloud files? We can help with Spring cleaning!

    Whether you use Dropbox, Drive, G-Suite, OneDrive, Gmail, Slack, Notion, or all of the above, Dokkio will organize your files for you. Try Dokkio (from the makers of PBworks) for free today.

  • Dokkio (from the makers of PBworks) was #2 on Product Hunt! Check out what people are saying by clicking here.


Codename Pinemango

Page history last edited by betty 12 years, 6 months ago


Introduction -- The Asterisk Applications API


Why are we doing this


See  custom essay writing for the details.

The following is an email sent to asterisk-dev explaining the impetus for this project:



> I know for fact that carriers in Israel hadn't adopted Asterisk fully
> due to its lack of RADIUS/DIAMETER support.
Before we can begin on this project, we need to change the way we think
about Asterisk.  Asterisk doesn't have perl, python, ruby, .Net, ftp,
smtp, POP3, pam, firefox, MS Word, Outlook, Exchange, SalesForce.com,
SugarCRM, 37signals, Google Docs, Excel, or Facebook support either.

There's two ways to fix this:
1) Fire up vi and write it all in C as a module for Asterisk.  This has
been the traditional approach, and the various features in Asterisk done
this way are testaments to the efforts and vitality of the community.  I
just happen to believe it's the wrong way to do it.
2) Give Asterisk a flexible programming API such that this functionality
can be done outside of Asterisk in a development framework.  Apache +
Rails is a great example of this.  Does Rails diminish the importance of
Apache?  It does a bit, but imagine how diminished Apache would be if
you couldn't use Rails with it because it didn't expose enough of an API.

Now, this doesn't mean that the #1 approach is going away.  Apache still
has mod_auth_radius.  All I'm asking for is the *ability* to do it via
#2, which doesn't exist in Asterisk today.


Overview of Issues with the Current Interfaces



  • Stuff and Things


Proposed New Architecture


The Asterisk Application Programming Interface (API) is a proposed architecture created with the goal of simplifying and unifying the various interfaces used today to create Asterisk applications.  Asterisk applications in this context are not Asterisk dialplan applications as they exist today.  This effort addresses interfaces that provide the ability to build applications that use Asterisk as the telephony engine.


Below is a graphic that represents the key layers of the proposed new architecture.



  • Following a discussion with oej on the mailing list, I agree that adding an AA layer is important. While the actual code may not be in there, the architecture should be put in place. However, I don't believe that a single AA layer is the right way to go, so consider the following diagram:

    The above will allow for an Authorization API to be created, with empty calls at the start of the development

    and we'll add functions and calls to it as we go along the way. -- Nir S


  • Judging from the latest responses on the mailing list and the importance of the subject, I believe that before approaching the actual problem of how to do it, we must first decide on what is actually related to what. Both oej and Tzafrir had brought up interesting points in relation to call control security, signalling access security and various other issues directly related to Asterisk internals. In my view, the API must first provide the basic security granularity for 3rd party telephony application developers (aka: AGI script writers and IVR developers). My thought is to seperate the single Authorization API into 2 distinct API structures, one used primarily for 3rd party application developers and the other used for direct connections into the core.

    Consider the following diagram (excuse the change of colors):

    In the above diagram, I've seperated the authorization API's, dictating that we first concentrate on the data_get, data_put, events and call_api which are currently not only lacking security, but also lack proper support. I'd really love to see a data_get interface, that would enable me to throw my Manager lookup callbacks, however, introducing a proper security structure for that would be amazing for phase 1. Then continue the work from that point onwards. I believe the issues indicated by Ph.1 - 3 can be accomplished using the current code base. Once we tackle the problem in that arena, we will be able to deduce what is required for ast_pbx and the hooks interfaces and then do it properly. -- Nir S

  • We can't simply put an authorization layer attached to the API, because many actions that potentially require authorization may happen indirectly. A channel may be generated. Two channels may be bridged. Channel may use a codec. Channel may use a function. A channel may initiate an AGI script or an external process.

  • As you note, in my view it is the channel that does everything. I think that this is how Asterisk is built. Channels hold the context of everything. If we have an authorization layer that is not strongly tied to what channels are authorized to do, we will have the same issues as we have today with the manager interface: the interface does not have the knowledge to manage authorization.

  • My basic perception of this is of a sort of an "operating system" where the channels are the processes and anybody that connects through an interface are users. -- Tzafrir



Asterisk Applications API Support Components


These six elements are needed in the core of asterisk to provide the functionality to the API modules to control all aspects of Asterisk.


Extensions and Application Execution (ast_pbx)


The PBX interfaces is the existing infrastructure that provides the following functionality:

  • Execution of pre-built Asterisk dialplan applications on channels.
  • Registration of Asterisk extension logic from some external representation (raw extensions.conf, AEL, CLI commands to add/remove extensions)
  • Provide an implementation of Asterisk extensions switching.
    • switch => ... in extensions.conf
    • This interface is already implemented in struct ast_switch.  (pbx_lua and pbx_dundi are example users)



  • res_api will likely take an asynchronous approach to spawning and monitoring diaplan applications
  • res_api will handle threading to not block on dialplan apps (IE: call app Dial in a separate thread)
  • It's likely that api components will provide an full ast_switch implementation instead of just a dialplan function like agi


Generic Event System (events)


The events subsystem will be the base for all manager events, as well as provide events to other components in asterisk such as CEL logging, MWI, and devicestate notifications.


The event subsystem has already been implemented.  Here is the relevant code for the core event system:

  • main/event.c
  • include/asterisk/event.h
  • include/asterisk/event_defs.h


Here is the doxygen documentation related to the existing events framework internal to Asterisk:


Changes Needed:

  • CEL events and Manager events need to be merged, and the IEs supplied need to be combined to the superset of everything that both manager or CEL (or some other customer might need).
    • By "merged", do you mean that more CEL events need to be added such that it provides just as much information (and eventually more) than the existing manager interface?  I'm just trying to understand what this is implying ... --Russell
    • I mean that manger would be built on top of the events subsystem and that the events in the CEL branch and the events in the manager2 branch would be merged to service both needs.  Of course, I wrote the above because I forgot that you favor keeping manager like it is and just leaving it alone, perhaps deprecating it away completely. -bmd


Data Retrieval Interface (data_get)


The data_get interface will supply an abstract way for modules to provide data to various components in asterisk including: manager, cli, dialplan, res_snmp, etc.  A namespace in asterisk will be used to reference the various providers of data, as well as a mechanism for discovering which namespaces and data are supplied.





  • res_snmp will have to map data namespaces to specific MIB OIDs.




The purpose of this mechanism is to enable an API for modifying all asterisk configuration, regardless of backend storage.  This will remove the need for asterisk configuration frameworks to have to generate config files.  While realtime allows some of this, the data_put interface solves the problem of changing the database underneath Asterisk, since Asterisk will be aware of all changes and be able to respond to them (eg: flush a sip_peer from the cache when it's deleted).


  • While I do agree that this methodology is required, this introduces an interesting problem of data consistency with multiple PUT actions. Let us imagine that two seperate data_put clients are currently modifying the same configuration back end, handling the same object in the configuration - which one is the right configuration? In addition, we would be required to create a proper user->backend->configuration_object locking mechanism to verify that applications are incapable of updating the same configuration as the same time. -- Nir S
  • I don't see the problem here.  We use mutexes all over Asterisk to deal with concurrency.  Since data_put is likely not going to need to be a hugely performant piece of code, we could wrap the whole thing in a mutex if we cared to. -bmd
  • Well, as long as you go about and granulate the mechanism to a user->backend->configuration_object->key_value

    level, than the mutex solution will do just fine. If the granulatry is at the configuration_object level, a simple mutex will not suffice. -- Nir S




Hooks are arbitrary callbacks within the internals of asterisk where external components can modify asterisk's behavior.  While the dialplan allows applications to control much of the asterisk behavior, hooks allow for business logic to be applied to situations that are not associated with a call (eg: a sip registration hook could allow time-goverened registration period), or for situations that occur during the execution of a diaplan application (eg: codec negotiation hook to apply business logic to codecs proposed in the middle of a Dial command, or a transfer hook to execute business logic when a SIP REINVITE is received).


call api


The call api encompasses all of the things available in the core of asterisk to modules for controlling calls.  There are two facets of the call api:


internal asterisk methods


API layer modules may want to directly call methods such as ast_do_masquerade(), or ast_hangup() in order to control the behavior of the system.


api-exported methods


Some modules may export specific methods to the API layer that facilitate calling directly by the frameworks.  An example of this is the manager command Originate, or the Bridge command.  Most manager commands that actually execute an action should be redefined as an api-exported method, such that they can be used by manager, the cli, as well as all of the other API layer interfaces such as mod_json.  There probably won't be much difference between the syntax of defining a manager command and defining an api-exported method, aside from the data returned will be more structured (ala data_get).


API Layer Modules


These modules will export the mechanisms of the API support components to external applications.




This module will provide a socket-based API to external applications.  Ideally, this interface will be abstracted in order to better provide an API contract with external customers.  This will allow us to potentially change the underlying support component implementations without breaking API compatability with third-party applications and frameworks.


language bindings


It's possible to embed a high-level language interpreter directly into asterisk which will be able to control all aspects of the PBX.  pbx_lua is an example that uses the existing struct ast_switch interface to implement a dialplan in lua.  Future language bindings will go beyond just the dialplan and be able to play a part in all aspects of Asterisk's behavior using the API Components.




Another API layer would be a thin RPC layer that would communicate over standard RPC mechanisms such as Java RMI, DBUS, CORBA, etc.




This is an API layer that implements an http server that delivers JSON-encoded data to http requests.


Things to Consider


  • what mechanism should we use to encode binary data for data_get or res_api interaction?
    • home-rolled
    • ASN.1 (see asn1c for a good C interface
    • Google Protocol Buffers
    • Thrift
      • Interesting question. I have to admit that I'm unfamiliar with GPB and Thrift, but after reading the information it would appear that GPB is much more mature than Thrift, at least on the face of it. I have to admit that after writing a couple of Facebook applications, I can honestly say that code that comes out of facebook, no matter how big they are, still is, usually, half baked. -- Nir S
      • I'm leaning towards ASN.1 via asn1c for res_api and probably russell's internal structure for internal data_get representation (unless asn.1 is usable for the internal stuff too) -bmd

  • Should res_api actually have pluggable transports?
    • Sean Bright brought up WCF with respect to this.  It may be worth looking at some design concepts here.


Comments (1)

Russell Bryant said

at 2:28 pm on Sep 27, 2008


You don't have permission to comment on this page.