API

An async ARI client can be created simply by the aioari.connect method. This will create a client based on the Swagger API downloaded from Asterisk.

The API is modeled into the Repository Pattern, as you would find in Domain Driven Design. Each Swagger Resource (a.k.a. API declaration) is mapped into a Repository object, which is provided as a field on the client (client.channels, client.bridges).

Responses from Asterisk are mapped into first-class objects, akin to Domain Objects in the Repository Pattern. These are provided both on the responses to RESTful API calls, and for fields from events received over the WebSocket.

Making REST calls

Each Repository Object provides methods which invoke the non-instance specific operations of the associated Swagger resource (bridges.list(), channels.get()). Instance specific methods are also provided, which require identity parameters to be passed along (channels.get(channelId=id)).

Instance specific methods are also provided on the Domain Objects (some_channel.hangup()).

Registering event callbacks

Asterisk may send asyncronous messages over a WebSocket to indicate events of interest to the application.

The Client object has an on_event method, which can be used to subscribe for specific events from Asterisk.

The first-class objects also have ‘on_event’ methods, which can subscribe to Stasis events relating to that object.

Object lifetime

The Repository Objects exist for the lifetime of the client that owns them.

Domain Objects are ephemeral, and not tied to the lifetime of the underlying object in Asterisk. Pratically, this means that if you call channels.get('1234') several times, you may get a different object back every time.

You may hold onto an instance of a Domain Object, but you should consider it to be stale. The data contained in the object may be out of date, but the methods on the object should still behave properly.

If you invoke a method on a stale Domain Object that no longer exists in Asterisk, you will get a HTTPError exception (404 Not Found).

Caveats

The dynamic methods exposed by Repository and Domain objects are, effectively, remote procedure calls. The current implementation is synchronous, which means that if anything were to happen to slow responses (slow network, packet loss, system load, etc.), then the entire application could be affected.

Examples

import asyncio
import aioari

client = await aioari.connect('http://localhost:8088/', 'hey', 'peekaboo')

def on_dtmf(channel, event):
    digit = event['digit']
    if digit == '#':
        channel.play(media='sound:goodbye')
        channel.continueInDialplan()
    elif digit == '*':
        channel.play(media='sound:asterisk-friend')
    else:
        channel.play(media='sound:digits/%s' % digit)


def on_start(channel, event):
    channel.on_event('ChannelDtmfReceived', on_dtmf)
    channel.answer()
    channel.play(media='sound:hello-world')


client.on_channel_event('StasisStart', on_start)

loop = asyncio.get_event_loop()
loop.run_until_complete(client.run(apps="hello"))

TODO

• Create asynchronous bindings that can be used with Twisted, Tornado, etc.

• Add support for Python 3