Asterisk 13: The Asterisk REST Interface (ARI)

Timelapse of City Street at Night
Profile picture of the author

Contributing Author

Asterisk 13 introduces changes to the Asterisk core that facilitate new and better APIs in Asterisk. In this blog post, we’ll begin to look at the new API that those core changes allowed — the Asterisk REST Interface (ARI).

A Brief History of Asterisk APIs

When Asterisk was first created back in 1999, its design was focused on being a stand-alone Private Branch eXchange (PBX) that you could configure via static configuration files. While this level of configuration is sufficient for many applications, for some domains, it is far more preferable to manipulate Asterisk via an external system. So, not long into the project, two APIs were added to Asterisk: the Asterisk Gateway Interface (AGI) and the Asterisk Manager Interface (AMI). These two interfaces have distinct purposes:

  1. AGI is analogous to CGI in Apache. AGI provides an interface between the Asterisk dialplan and an external program that wants to manipulate a channel in the dialplan. The interface is synchronous — actions taken on a channel from an AGI block and do not return until the action is completed.
  2. AMI provides a mechanism to control where channels execute in the dialplan. Unlike AGI, AMI is an asynchronous, event-driven interface. For the most part, AMI does not provide mechanisms to control channel execution — rather, it provides information about the state of the channels and where the channels are executing.

Both of these interfaces are powerful and opened up a wide range of integration possibilities. Using AGI, remote dialplan execution could be enabled, which allowed developers to control channels in Asterisk using PHP, Python, Java, and other languages. Using AMI, the state of Asterisk could be displayed, calls initiated, and the location of channels controlled. Using both APIs together, complex applications using Asterisk as the engine could be developed.
However, while AMI is good at call control and AGI is good at allowing a remote process to execute dialplan applications, neither of these APIs were designed to let a developer build their own custom communications application. Fundamentally, neither API exposes the kinds of communications primitives that exist in Asterisk needed to easily build such an application. That wasn’t their intended purpose.
So, the Asterisk Developer Community set out to build a better API that would make it easier to build custom communications applications. ARI was the result of this effort.

ARI: An API for Building Communications Applications

ARI allows application developers to build rich, custom communications applications in the language of their choice. ARI exposes the raw primitive objects in Asterisk normally reserved for C modules — channels, bridges, endpoints, media, etc. — through an intuitive REST interface. As an asynchronous interface, ARI conveys the state of the objects being controlled by the user via JSON events over a WebSocket.
By handing control of the fundamental building blocks in Asterisk over to all developers — regardless of their language choice — Asterisk becomes an engine of communication, with the business logic of how things should communicate deferred to the application using Asterisk.
ARI is not a replacement for AMI or AGI. Rather, it is a complementary API:

  • AGI allows you to control dialplan execution of a channel
  • AMI allows you to manage calls at a high level
  • ARI allows you to replace dialplan applications with your own custom communications application

ARI is not about telling a channel to execute the VoiceMail dialplan application or redirecting a channel in the dialplan to a VoiceMail extension.

It is about letting you build your own VoiceMail application.

For more information about getting started with the ARI, check out the Asterisk wiki.

Stay Informed! Click to Subscribe Now!
Scroll to Top