Asterisk REST Interface(ARI)

The Evolution of Asterisk APIs（asterisk API的演变）

当Asterisk于1999首次创建时，其设计主要在于成为一个独立的Private Branch eXchange (PBX):可以通过静态.conf文件进行配置。呼叫控制通过特定.conf文件:extension.conf实现，成为"dialplan"。dialplan脚本告送asterisk呼叫中调用那些application，并且根据用户通过手机执行的操作做出逻辑决策。该模块长期以来运行良好-当然他现在更加灵活，dialplan应用提供了大量功能。
然而，这些dialplan applications仍然是用C语言编写的。因为这些application是直接作用于asteirsk的原生函数，并且非常强大。他们可以访问通道，媒体，桥接，终端以及其他对象用于电话通信。然而，虽然强大，存在现有的applicaition不能满足的业务用例。在过去，如果现有的dialplan applicaiton不能满足你需要的功能，实际上只有一个解决方案：用C写一个补丁-可能是向应用程序添加一个参数以调整行为-并将其提交给项目。如果你不能用C语言编写这个功能，那么就会陷入困境。

Enter AMI and AGI

项目成立不久，向asterisk添加了两个应用程序编程接口(API):the Asterisk Gateway Interface(AGI)和the Asterisk Manager Interface(AMI)。这些接口有不同的用途：

• AGI类似于Apache的CGI。AGI在asterisk dialplan和想要操作dialplan中channel的外部应用之间提供接口。通常，接口是同步的-从AGI块在通道上执行并且知道操作完成才执行。
• AMI提供了一种机制来控制channel在dialplan中的执行位置。与AGI不同，AMI是异步的，事件驱动的接口。在大多数情况下，AMI不提供控制channel执行的机制-而是提供有关通道状态的信息以及控制channel执行位置。
  这两种接口都很强大并且开辟了广泛的集成可能性。使用AGI,可以远程执行dialplan：这允许开发人员将Asterisk与PHP,Python,Java和其他应用集成。使用AMI，可以获取asterisk的状态，初始化的呼叫，以及控制通道的位置。将两种API结合使用，使用asterisk可以实现复杂的应用程序。
  但是使用ami和agi创建自定义的通信应用存在一些缺点：
• AGI是同步的，当在channel上执行asterisk 操作时，他会阻塞线程以为AGI提供服务。当创建通信应用程序时，需要响应channel的更改（DTMF,channel state等等）；AGI本身很难做到这一点。协调ami事件非常有挑战性。
• dialplan是受限的。即使使用AMI和AGI,基本操作也仅限于在channel上执行的操作。虽然功能强大，但是asterisk中其他的原函数是无法通过API获取的:bridges,endpoints,device state message waiting indications and the actual media on channels themselves。通过AMI和AGI控制这些可能很困难，并且通常可能涉及负责的dialplan 操作来实现。
• 最后，AMI和AGI都是asterisk项目的早期创建的，并且是他们时代的产品。虽然两者都是功能强大的接口，当时的技术在现在没有被广泛使用。
  SOAP, XML/JSON-RPC,和REST等概念都没有广泛使用。因此，新API可以更直观，更容易采用，从而加快asterisk用户的开发速度。
  因此，在asterisk12之前，如果你想要自定义同行应用，可以：
• 用C写一个asterisk模块
• 使用AGI和AMI写一个自定义应用，费力的将两个API结合在一起

ARI: An Interface for Communications Applications

Asterisk RESTful Interface(ARI)就是为了解决这些问题。虽然AMI擅长控制呼叫并且AGI擅长远程执行dialplan应用，但这些API都不是为了让开发人员构建自己的自定义通信应用。ARI是异步API：允许开发人员通过直观的REST接口公开asterisk的原始元素-channels,bridges,endpoints,media等等。用户控制的对象的状态可以通过websocket上的JSON事件传递。
这些资源传统上是asterisk c模块的范畴。通过将这些资源的控制交给所有的开发人员-无论选择何种开发语言-asterisk成为通信的引擎，通信的业务逻辑实现由使用asteirsk的应用控制。

ARI 不是告送channel去执行一个voiceMail dialplan应用也不是重定向dialplan中的channel到VoiceMail.而是让你构建自己的voiceMail应用程序。

ARI Fundamentals（ARI基础知识）

ARI由三个不同的部分组成-对于所有的意图和目的-相互关联共同作用。他们是：

• A RESTful interface：客户端可以用来控制asterisk的资源。
• A Websocket：以json格式发送asterisk中资源的事件到客户端
• The Stasis dialplan application：将asterisk channel的控制权移交给客户端。
  这三个部分协调工作允许开发人员操纵和控制asterisk中的基本资源并 够条件自己的通信应用。

开发文档

你可以在wiki上找到有关ARI的开发和架构的一些历史文档。

What is REST?

Representational State Transfer(REST)是一种软件架构风格。有几个特点：

• 使用客户端-服务器模式执行通信。
• 沟通是无状态的。服务器不在请求之间存储客户端状态。
• 连接是分层的，允许中间人协调路由和负载均衡。
• 统一的接口，请求中标识资源，消息是自描述的，等等。
  ARI并不严格遵守REST API。作为独立的应用，asterisk的状态可能在客户端通过ARI的请求之外状态发生变更。例如，SIP phone可能挂断，asterisk将挂断channel，-即使客户没有通过ARI告送asterisk挂断SIP phone。asterisk是异步，有状态的：因此，ARI 是RESTful。It attempts to follow the tenants of REST as best as it can, without getting bogged down in philosophical constraints.所以并不严格遵守REST API。

What is a WebSocket?

websocket是相对比较新的一种协议标准(RFC 6455)：支持客户端和服务器之间的双向通信。该协议的主要目的是为基于浏览器需要和服务器双向通信的应用程序提供一种机制：而不依赖于http长轮序或者其他非标准机制。
对于ARI,websocket连接用于将异步事件从asterisk传递到客户端。
这些事件和RESTful接口有关但是技术上相独立。这允许asterisk通知客户端资源状态的变更：由客户端通过ARI所做的更改导致。

What is Stasis?

Stasis是一个asterisk dialplan应用。
这是一种将channel的控制权从dialplan(控制channel的传统方式)到ARI和客户端。通常，ARI应用操作Stasis dialplan应用中的channel以及asterisk的其他资源。ARI不能控制不在Stasis dialplan应用的channel-毕竟ARI的目的是构建自己的dialplan引用，而不是已有的channel。

Diving Deeper

这里有很多页面：探索ARI中可用的不同资源以及可以使用它们构建的示例。通常这些示例假设如下：

• 已经使用chan_pjsip或者chan_sip注册一些话机到asterisk
• 拥有一些配置asterisk的基础知识
• 了解Python, javaScript,获取其他一些更高级的编程语言的基础知识。
  大部分示例不会直接构建HTTP REST调用，因为已经编写了很多长勇的有效的库来封装这些函数。可用库罗列在下面。

Where to get the examples

该页面上的所有例子都可以在github上找到，可以去check out。

ARI Libraries

有关Asterisk Rest Interface库以及架构的列表请参阅ARI Libraries页面。

Recommended Practices（推荐做法）

Don’t access ARI directly from a web page

从网页直接使用ARI进行开发非常方便，例如使用Swagger-UI甚至滥用Websocket echo demo来获取ARI Websocket。
但是，请不要在生产应用中这样做。这类似于直接从网页访问你的数据库。你需要在自己的应用程序服务器（可以处理安全，日志，多租户以及其他的不属于通信引擎的事物）后面隐藏Asterisk。

Use an abstraction layer（使用抽象层）

ARI最吸引人的地方是发送请求如此容易。但是对于开发有力的并不对生产有利。
请不要在你的应用中使用大量的直接的HTTP调用。需要着重处理api调用的cross-cutting问题。现在，唯一的问题是身份验证。但随着API的发展，其他问题(例如版本控制)也越来越重要。
请注意抽象层不能（也不应该）太复杂。客户端API甚至可以作为GET,POST,和DELETE的简单封装，解决cross-cutting问题。asterisk TestSuit 是一个非常简单的抽象库：可以这样使用

ari = ARI('localhost', ('username', 'password'))
 
# Hang up all channels
channels = ari.get('channels')
for channel in channels:
    ari.delete('channels', channel['id'])

换句话说：使用上面的库或者编写一个自己的库。