<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2176/25/9/_/styles/combined.css?spaceKey=AST&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/AST/Asterisk+12+API+Improvements">Asterisk 12 API Improvements</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~dlee">David M. Lee</a>
</h4>
<div id="versionComment">
<b>Comment:</b>
Updated design section, so that it's no longer a lie<br />
</div>
<br/>
<h4>Changes (53)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >The password may be stored as plaintext, or can be stored using [crypt(3)|http://man7.org/linux/man-pages/man3/crypt.3.html]. A crypted password can be generated using the {{mkpasswd -m sha-512}} command. <br> <br></td></tr>
<tr><td class="diff-unchanged" >h1. Design <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h2. Pretty Picture <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{anchor:message-bus} <br>h2. {{stasis.c}} - Stasis Message Bus <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Visually, this is how it all fits together. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">*Header*: {{asterisk/stasis.h}} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">{flowchart} <br>edge [arrowhead="none"]; <br>node [width=1.5]; <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The [Stasis Message Bus|AST:Stasis Message Bus] is how message producers and consumers are decoupled within the new API work. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">{ rank = same; manager; "stasis-core"; "stasis-http"; } <br>{ rank = same; "Action Callbacks"; "Stasis Callbacks"; } <br>{ rank = same; "module X"; "stasis-façade"; } <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Please see the [API docs|http://doxygen.asterisk.org/trunk/stasis.html] and the [wiki page|AST:Stasis Message Bus] for further details. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">manager -> "Action Callbacks" [arrowhead="vee", style="dashed"] <br>"Action Callbacks" -> "module X" [arrowtail="o", dir="back"] <br>"module X" -> "Internal APIs" [arrowhead="o"] <br>"stasis-core" -> "Stasis Callbacks" [arrowhead="vee", style="dashed"] <br>"Stasis Callbacks" -> "stasis-façade" [arrowtail="o", dir="back"] <br>"stasis-façade" -> "Action Callbacks" [arrowhead="vee", style="dashed"] <br>"stasis-façade" -> "Internal APIs" [arrowhead="vee", style="dashed"] <br>"stasis-core" -> "stasis-http" [arrowtail="vee", dir="back"] <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">h2. {{res_stasis.c}} - Stasis Application API <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">"stasis-http" [fillcolor=green] <br>"stasis-core" [fillcolor=green] <br>"Stasis Callbacks" [fillcolor=green] <br>"stasis-façade" [fillcolor=green] <br>{flowchart} <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">*Header*: {{asterisk/stasis_app.h}} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h2. Existing Components <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">High level application API's for Asterisk. The [Message Bus|#message-bus] provides a read-only view into Asterisk. This API gives you high level manipulation. The functions in this API should correspond roughly one-to-one to the sorts of methods you would put into an external API. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Stasis will introduce several new modules into Asterisk. To understand how they interact with the existing system, it helps to know some of the existing components. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Please see the [API docs|http://doxygen.asterisk.org/trunk/d8/d9c/stasis__app_8h.html] for further details.. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3. manager <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">h2. {{app_stasis.c}} - Stasis Dialplan Application <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Existing AMI implementation. Modules may register callbacks for AMI actions, and dispatch AMI events via this component. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">*Application*: Stasis <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3. Action Callbacks <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The {{app\_stasis.so}} module simply exports the {{res\_stasis.so}} functionality as a dialplan application. This allows you to send channels to a Stasis application from within the dialplan. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Existing 'interfaces' for implementing AMI Actions. And by 'interface', I mean callback functions. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{code:none} <br>; Send channel to the 'Queue' application, with the args 'enqueue,sales' <br>exten => 7001,1,Stasis(Queue,enqueue,sales) <br>{code} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3. Existing modules <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">h2. {{stasis_\{channels,bridges,endpoints\}.c}} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">An existing Asterisk module. It already has functions that implements AMI action handlers, and dispatch AMI events. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">*Headers*: {{stasis_\{channels,bridges,endpoints\}.h}} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3. Internal API's <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Channels, endpoints and bridges will have their own Stasis topics and messages for publishing state and event messages about themselves. Each object also has a _snapshot_, which is a immutable struct representing the state of the underlying object at a particular point in time. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Internal state and API's exposed within Asterisk, but not necessarily exposed to the outside world via AMI. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Each object has its own topic, to which it posts snapshots and messages regarding events that happen to that object. These messages are all forwarded to an aggregation topic ({{ast\_\{channel,endpoint,bridge}\_topic\_all}}), which is cached by a caching topic ({{ast\_\{channel,endpoint,bridge}\_topic\_all\_cached}}). <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h2. New Components <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The aggregation and caching topics allow for components that need to monitor the overall state of the system (such as Manager). The caching topics allows components to query for the most recent snapshot of an object without querying the actual object itself. The reduces contention on the object itself, and reduces the opportunities for deadlock. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3. res_stasis_core <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">See the [API docs|http://doxygen.asterisk.org/trunk/df/deb/group__StasisTopicsAndMessages.html] for further details. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Core logic for the Stasis framework. This is a coordination layer between protocol bindings (as in stasis-http) and the underlying implementations in Asterisk modules. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">h2. {{manager_\{channels,bridges,endpoints\}.c}} - Existing component refactoring. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The separation of responsibilities between stasis-core and stasis-http keeps the door open for other protocol bindings to be built upon the Stasis API's. While the exact details of how stasis-core exposes the internal API are not defined, at the moment we are leaning towards a generic message bus. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Existing Manager events and CLI commands can (and should) be refactored to receive events from the appropriate aggregator topics, and retrieve state from the cache topics. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3. res_stasis_http <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The topics and messages for the main components of Asterisk are defined in {{main/stasis\_\{channel,endpoint,bridge}.c}}. The refactored Manager code will be implemented in {{main/manager\_\{channel,endpoint,bridge}.c}}. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Binding between Stasis and HTTP. While other Stasis bindings are possible, this design allows them to be brought up in addition to the HTTP binding. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">h2. Stasis RESTful API <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3. res_stasis_facade <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">*API docs*: {{rest-api}} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">This allows us to manage existing Asterisk modules without changing them. This wrapper will use the interfaces exposed by modules, taking advantage of both AMI handlers and internal API's to get at richer state information. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The RESTful Stasis HTTP implementation is broken down into several components. Much of the boiler plate code declaring routes and parsing parameters is done by code generated by the API docs. The generated code can be regenerated by running {{make stasis-stubs}}. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">By reducing the amount of change required for existing modules to support Stasis, we reduce the risk of Stasis-induced bugs. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">h3. {{res_stasis_http.c}} - Request handling and routing <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">As an additional benefit, if we can keep changes to existing code to a minimum, Stasis may be made available as a patch for Asterisk 11. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">*Header*: {{asterisk/stasis\_http.h}} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The {{res\_stasis\_http.so}} module has the common code for handling and routing requests. HTTP resource modules register themselves with the RESTful API by using the {{stasis_http_add_handler()}} and {{stasis_http_remove_handler()}} functions. <br> <br>h3. {{res_stasis_http_\{resource\}.c}} (generated) <br> <br>The structures declaring the routing for requests for a specific resource, and callbacks for parsing request arguments for the request. <br> <br>h3. {{stasis_http/resource_\{resource\}.c}} <br> <br>*Header*: {{stasis_http/resource_\{resource\}.h}} (generated) <br> <br>Implementation code for RESTful HTTP requests. The bulk of this code should be in consuming the request and producing the response. The bulk of the logic to carry out the request belongs in {{res_stasis.so}}, or in the underlying component. By keeping the HTTP modules free of business logic, we give ourselves a better shot at implementing other API bindings in a way that the different interfaces actually act consistently. <br> <br></td></tr>
<tr><td class="diff-unchanged" >h1. Test Plan <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>This page is under development; expect missing and incomplete information. Still, feel free to discuss on <a href="http://lists.digium.com/mailman/listinfo/asterisk-dev" class="external-link" rel="nofollow">asterisk-dev</a>.</td></tr></table></div>
<div>
<ul>
<li><a href='#Asterisk12APIImprovements-ProjectOverview'>1. Project Overview</a></li>
<li><a href='#Asterisk12APIImprovements-RequirementsandSpecification'>2. Requirements and Specification</a></li>
<ul>
<li><a href='#Asterisk12APIImprovements-StasisRequirements'>2.1. Stasis Requirements</a></li>
<ul>
<li><a href='#Asterisk12APIImprovements-AuthorizationRequirements'>2.1.1. Authorization Requirements</a></li>
</ul>
<li><a href='#Asterisk12APIImprovements-InternalImprovements'>2.2. Internal Improvements</a></li>
<li><a href='#Asterisk12APIImprovements-UseCases'>2.3. Use Cases</a></li>
<ul>
<li><a href='#Asterisk12APIImprovements-SummaryLevel'>2.3.1. Summary Level</a></li>
<li><a href='#Asterisk12APIImprovements-UserLevel'>2.3.2. User Level</a></li>
<li><a href='#Asterisk12APIImprovements-SubfunctionLevel'>2.3.3. Sub-function Level</a></li>
</ul>
<li><a href='#Asterisk12APIImprovements-Guidelines'>2.4. Guidelines</a></li>
<ul>
<li><a href='#Asterisk12APIImprovements-PBXvs.Toolkit'>2.4.1. PBX vs. Toolkit</a></li>
<li><a href='#Asterisk12APIImprovements-ConventionoverConfiguration'>2.4.2. Convention over Configuration</a></li>
</ul>
<li><a href='#Asterisk12APIImprovements-Configuration'>2.5. Configuration</a></li>
<ul>
<li><a href='#Asterisk12APIImprovements-stasishttp.conf'>2.5.1. stasis-http.conf</a></li>
<li><a href='#Asterisk12APIImprovements-stasiscore.conf'>2.5.2. stasis-core.conf</a></li>
<li><a href='#Asterisk12APIImprovements-RealTimeschemas'>2.5.3. RealTime schemas</a></li>
</ul>
<li><a href='#Asterisk12APIImprovements-APIs'>2.6. APIs</a></li>
<ul>
<li><a href='#Asterisk12APIImprovements-DialplanApplications'>2.6.1. Dialplan Applications</a></li>
<li><a href='#Asterisk12APIImprovements-RESTfulHTTPAPI'>2.6.2. RESTful HTTP API</a></li>
</ul>
</ul>
<li><a href='#Asterisk12APIImprovements-Design'>3. Design</a></li>
<ul>
<li><a href='#Asterisk12APIImprovements-%7B%7Bstasis.c%7D%7DStasisMessageBus'>3.1. <tt>stasis.c</tt> - Stasis Message Bus</a></li>
<li><a href='#Asterisk12APIImprovements-%7B%7Bresstasis.c%7D%7DStasisApplicationAPI'>3.2. <tt>res_stasis.c</tt> - Stasis Application API</a></li>
<li><a href='#Asterisk12APIImprovements-%7B%7Bappstasis.c%7D%7DStasisDialplanApplication'>3.3. <tt>app_stasis.c</tt> - Stasis Dialplan Application</a></li>
<li><a href='#Asterisk12APIImprovements-%7B%7Bstasis%5C.c%7D%7D'>3.4. <tt>stasis_{channels,bridges,endpoints}.c</tt></a></li>
<li><a href='#Asterisk12APIImprovements-%7B%7Bmanager%5C.c%7D%7DExistingcomponentrefactoring.'>3.5. <tt>manager_{channels,bridges,endpoints}.c</tt> - Existing component refactoring.</a></li>
<li><a href='#Asterisk12APIImprovements-StasisRESTfulAPI'>3.6. Stasis RESTful API</a></li>
<ul>
<li><a href='#Asterisk12APIImprovements-%7B%7Bresstasishttp.c%7D%7DRequesthandlingandrouting'>3.6.1. <tt>res_stasis_http.c</tt> - Request handling and routing</a></li>
<li><a href='#Asterisk12APIImprovements-%7B%7Bresstasishttp%5C.c%7D%7D%28generated%29'>3.6.2. <tt>res_stasis_http_{resource}.c</tt> (generated)</a></li>
<li><a href='#Asterisk12APIImprovements-%7B%7Bstasishttp%2Fresource%5C.c%7D%7D'>3.6.3. <tt>stasis_http/resource_{resource}.c</tt></a></li>
</ul>
</ul>
<li><a href='#Asterisk12APIImprovements-TestPlan'>4. Test Plan</a></li>
<li><a href='#Asterisk12APIImprovements-ProjectPlanning'>5. Project Planning</a></li>
<ul>
<li><a href='#Asterisk12APIImprovements-JIRAIssues'>5.1. JIRA Issues</a></li>
<li><a href='#Asterisk12APIImprovements-Contributors'>5.2. Contributors</a></li>
</ul>
<li><a href='#Asterisk12APIImprovements-ReferenceInformation'>6. Reference Information</a></li>
<li><a href='#Asterisk12APIImprovements-Footnotes'>7. Footnotes</a></li>
</ul></div>
<h1><a name="Asterisk12APIImprovements-ProjectOverview"></a>1. Project Overview</h1>
<p>While Asterisk has a number of interfaces one could use for building telephony applications, they suffer from several significant problems.</p>
<ul>
<li>Channels identifiers are not stable. Some operations (like <a href="/wiki/display/AST/Asterisk+11+ManagerEvent_Masquerade" title="Asterisk 11 ManagerEvent_Masquerade">masquerades</a>) will change the id out from under you.</li>
<li>The protocols (AMI and AGI) are non-standard and poorly documented, making them difficult to work with.</li>
<li>AMI's message format is restricted to simple name/value pairs. Commands that need to pass back lists or structured data are very hackish.</li>
<li>AMI event filtering is very course grained, and established in configuration instead of at runtime. This has lead to some creative solutions to dealing with the flood of events (most of which are not of interest).</li>
<li>AGI is a synchronous interface, which really hinders making truly interactive applications.
<ul>
<li>While AsyncAGI attempts to address this issue, it is an asynchronous wrapper around a synchronous implementation. Commands queue up after one another, and are not interruptible, leading to many of the same problems with AGI or FastAGI.</li>
</ul>
</li>
<li>Internally, AMI events are formatted into strings at the time they are created. This makes it very difficult to do anything with the events, except send them out AMI connections. This also makes using different protocol formats difficult.</li>
<li>Different interfaces tend to implement the same logical command in different ways.</li>
</ul>
<p>We're going to start with fixing one of the most glaring problems with the current APIs: <a href="https://issues.asterisk.org/jira/browse/ASTERISK-20725" class="external-link" rel="nofollow">add a stable identifier to channels</a>, and use that identifier consistently throughout AMI. This solves a big problem for current AMI+AGI based applications.</p>
<p>Unfortunately, solving some of the larger problems would be very intrusive with the current API's, and introduce a host of breaking changes. Some are so fundamental, we would essentially be rewriting the interface. That's not acceptable; the current API's aren't going anywhere anytime soon.</p>
<p>This leads us down the path of adding a new interface to Asterisk. We've got some time to put some though into this, so let's do it right. Since things are easier to talk about when they have a name, the new API work has the working title <a href="#Asterisk12APIImprovements-badname">Stasis</a>.</p>
<p>We want the API to be familiar and approachable to developers. We don't want to force them to use C. In fact, we don't want to force them to use any particular programming language; the API should be accessible from the language and platform of their choice.</p>
<p>The API should be relatively high level, and not get stuck down in the details of what's happening inside of Asterisk. Asterisk may go through all sorts of shenanigans to do what it needs to do, but the API should provide a nice, clean abstraction.</p>
<p>In building out the new API, we don't want to repeat past mistakes by re-implement the same functionality several times in slightly different ways. There should be a single core implementation, that all of the API's use. This would improve consistency between the API's and reduce code duplication.</p>
<p>To accomplish this, Stasis will be a set of new modules for providing control and management interfaces into Asterisk. While Stasis will initially be focused on third party call control and monitoring, it should be extensible enough to provide configuration and provisioning API's in the future.</p>
<p>Internally to Asterisk, <tt>stasis-core</tt> will provide a message bus for interfacing with Asterisk objects. The <tt>stasis-http</tt> component will be built upon this message bus to expose a RESTful API, also utilizing WebSockets for asynchronous communication to the external applications.</p>
<p>The split between <tt>stasis-core</tt> and <tt>stasis-http</tt> should allow for other protocol bindings to be added in the future. This could even go so far as replacing the existing API's with Stasis implementations.</p>
<p>The selection of HTTP as the first binding for Stasis allows for very broad appeal, ease of use, and simplicity for writing client libraries to make it easier to write applications to the API.</p>
<h1><a name="Asterisk12APIImprovements-RequirementsandSpecification"></a>2. Requirements and Specification</h1>
<h2><a name="Asterisk12APIImprovements-StasisRequirements"></a>2.1. Stasis Requirements</h2>
<ul>
<li><b>Asynchronous Everything</b> - Most applications need to be able to interrupt activities, and receive events as they happen. Blocking operations are the devil.</li>
<li><b>Version Stability</b> - This is important. Like, really important. The current mechanisms may change dramatically between releases, which causes developers/integrators/etc. to keep running on older versions of Asterisk than anyone would like.</li>
<li><b>Interoperability</b> - Stasis must work in a variety of environments, detailed below.
<ul>
<li><b>Programming Language</b> - Stasis applications should be able to be easily written in a variety of languages.</li>
</ul>
</li>
<li><b>Security</b> - Reasonable security measures should be taken.
<ul>
<li>Encryption: Since the API should not be accessible on a public network, encryption is not high in the priority list.
<ul>
<li>Even if connections are plain text, reasonable precautions should be taken with sensitive information (e.g. use challenge handshakes for authentication instead of passing plaintext passwords over the wire).</li>
<li>If a binding protocol (say, HTTP) supports encryption (say, HTTPS), then it should be supported for Stasis as well.<br/>
Not needed immediately, and way down on the priority list.</li>
</ul>
</li>
<li>Authentication: Client only authentication is sufficient. Should not be any more complicated than passwords/pre-shared secrets.</li>
<li>Authorization: See <a href="#Asterisk12APIImprovements-StasisAuthorizationRequirements">below</a>.</li>
</ul>
</li>
</ul>
<h3><a name="Asterisk12APIImprovements-AuthorizationRequirements"></a>2.1.1. Authorization Requirements</h3>
<p>Unfortunately, authorization is a tricky subject.</p>
<p>There are many different schemes for implementing authorization, and we've learned that if you're not careful you can end up with a scheme that doesn't provide the value that you hoped for, and is more costly than you expected. And this cost shows up in the complexity of both the implementation and the API.</p>
<p>It's also important to understand who you are authorizing. In the case of the API, we are authorizing applications for API access; not (necessarily) the end users of the phone system. It's somewhat similar to the three tier client/application/database relationship. The database authenticates the application, and determines what data the application can access. The application authenticates the client, and determines what subset of that data it exposes to the client. It's not a perfect comparison, but you get the idea.</p>
<p>Possible use cases to consider:</p>
<ul>
<li><b>Host multiple companies in one PBX</b> - "which channels are one particular user (or group) allowed to follow, manipulate and originate".</li>
<li><b>Read only applications</b> - A monitoring application should not be able to affect the state of the system.</li>
</ul>
<h2><a name="Asterisk12APIImprovements-InternalImprovements"></a>2.2. Internal Improvements</h2>
<ul>
<li><b>Stable channel identifier</b> - this is necessary for a reasonable Stasis API. Since so much of the world still depends on AMI, it should be updated to allow the stable id to be used in place of the current channel id</li>
<li><b>AMI Event Structure</b> - AMI events should be generated into a key/value object pair instead of the <tt>printf</tt>-style string formatting currently used. This would allow Stasis to reuse the existing events.</li>
<li><b>Improved implementation consistency</b> - While not something we would address in the initial Stasis work, existing disparate implementations could be reworked to use a single, consistent <tt>stasis-core</tt> implementation.</li>
<li><b>Fix AMI Bridge Events</b>
<ul>
<li>Current event precludes multi-party bridges (Only has <tt>Channel1</tt> and <tt>Channel2</tt>)</li>
<li>Some events in the system result in spurious Bridge events (such as <a href="https://issues.asterisk.org/jira/browse/ASTERISK-18639" class="external-link" rel="nofollow">DTMF</a>)</li>
</ul>
</li>
</ul>
<h2><a name="Asterisk12APIImprovements-UseCases"></a>2.3. Use Cases</h2>
<p>Note that at this point this it the list of <em>candidate</em> use cases. Which ones we get to, and in what priority, have not been determined yet.</p>
<h3><a name="Asterisk12APIImprovements-SummaryLevel"></a>2.3.1. Summary Level</h3>
<p>Highest level use cases; more or less applications that could be build on top of Stasis.</p>
<ul>
<li><b>Standard two party call</b> - Very standard use case for Asterisk.</li>
<li><b>Conference</b> - Multi-participant calls, in which media from one endpoint may be sent to two or more endpoints.
<ul>
<li>Some participants may control the conference via DTMF key presses</li>
<li>Some participants may be muted</li>
<li>Indicate who is speaking</li>
</ul>
</li>
<li><b>IVR</b> - Interactive Voice Response.
<ul>
<li>Plays media to caller</li>
<li>Detects DTMF key presses from caller</li>
<li>Record media from caller</li>
</ul>
</li>
<li><b>Queue</b> - Call dispatch queue.
<ul>
<li>Get presence information from queue agents</li>
<li>Originate calls to agents as needed</li>
<li>When agent answers, bridge to most appropriate call from queue</li>
<li>May add supervisor to agent/caller conversation</li>
</ul>
</li>
<li><b>Voicemail</b>
<ul>
<li>Record audio from caller</li>
<li>Playback recorded audio</li>
<li>Detect DTMF for media control (fast forward, skip, delete)</li>
</ul>
</li>
</ul>
<h3><a name="Asterisk12APIImprovements-UserLevel"></a>2.3.2. User Level</h3>
<ul>
<li><b>Answer</b> - An application may answer a ringing channel.</li>
<li><b>Hangup/Reject</b> - An application may hangup an active channel, or reject a ringing channel.</li>
<li><b>Return to dialplan</b> - An application may send a channel back to the dialplan to continue processing.</li>
<li><b>Originate</b> - An application may originate a new channel.</li>
<li><b>DTMF Detection</b> - DTMF, and other channel events.</li>
<li><b>Bridge</b> - Two or more channels may be bridged together, so that media from any channel may be mixed and sent to the others
<ul>
<li><b>Speaker Events</b> - Events indicating which channel(s) on the bridge are speaking.</li>
</ul>
</li>
<li><b>Play</b> - An application may specify media to be played on a channel.</li>
<li><b>Presence</b> - An application may query the presence state of endpoints, and subscribe to presence updates.</li>
<li><b>Record</b> - An application may record the media from a channel/bridge.</li>
<li><b>BLF</b> - The application may light up the BLF on an endpoint.</li>
</ul>
<h3><a name="Asterisk12APIImprovements-SubfunctionLevel"></a>2.3.3. Sub-function Level</h3>
<ul>
<li><b>Media Control</b> - During the playback of media, the application may issue fine-grained media control commands. (fast forward, pause, stop, etc.)</li>
<li><b>Mute participant</b> - Within a bridge, an application may (un)mute individual channels, controlling which media streams are mixed and sent to other participants.</li>
</ul>
<h2><a name="Asterisk12APIImprovements-Guidelines"></a>2.4. Guidelines</h2>
<h3><a name="Asterisk12APIImprovements-PBXvs.Toolkit"></a>2.4.1. PBX vs. Toolkit</h3>
<p>From the README in trunk: "Asterisk is an Open Source PBX and telephony toolkit." However, whether or not we are PBX-centric has implications for the API.</p>
<p>Currently, Asterisk leans more toward being a toolkit than a PBX. There is a very loose coupling between extensions and endpoints, as is typically defined by dialplan code in the extensions.conf file. There is no concept of 'inside' versus 'outside', unless you put it in the dialplan yourself. There is no standard definition of a 'call', or a 'user'. All of these vary depending upon your application, and being able to be applied to a variety of applications is what has made Asterisk so successful.</p>
<p>However, the primary application Asterisk is applied to is being a PBX. It is important that developers writing PBX applications aren't bogged down with general telephony toolkit details.</p>
<p>So while the PBX use cases are important, they should not undermine the general purpose toolkit use cases. Largely, this will influence default values and conventions of the API.</p>
<h3><a name="Asterisk12APIImprovements-ConventionoverConfiguration"></a>2.4.2. Convention over Configuration</h3>
<p>Continuing on with the theme of PBX vs. Toolkit, the API should adopt an approach of convention over configuration: reasonable defaults should be used wherever possible. Configuration should be possible, allowing users to specify their own values in place of these defaults.</p>
<h2><a name="Asterisk12APIImprovements-Configuration"></a>2.5. Configuration</h2>
<h3><a name="Asterisk12APIImprovements-stasishttp.conf"></a>2.5.1. stasis-http.conf</h3>
<p>Configuration for the HTTP binding for Stasis.</p>
<h4><a name="Asterisk12APIImprovements-%5Cgeneral%5C"></a>2.5.1.1. [general]</h4>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Parameter </th>
<th class='confluenceTh'> Description </th>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Default Value </th>
</tr>
<tr>
<td class='confluenceTd'> enabled </td>
<td class='confluenceTd'> Turns Stasis HTTP binding on or off <br class="atl-forced-newline" />
HTTP server must be enabled in http.conf for this to take effect </td>
<td class='confluenceTd'> Boolean </td>
<td class='confluenceTd'> yes </td>
</tr>
<tr>
<td class='confluenceTd'> pretty </td>
<td class='confluenceTd'> When set to yes, responses from stasis-http are formatted to be human readable </td>
<td class='confluenceTd'> Boolean </td>
<td class='confluenceTd'> no </td>
</tr>
<tr>
<td class='confluenceTd'> allowed_origins </td>
<td class='confluenceTd'> Comma separated list of allowed origins, for Cross-Origin Resource Sharing. May be set to <tt>*</tt> to allow all origins. </td>
<td class='confluenceTd'> Comma separated strings </td>
<td class='confluenceTd'> </td>
</tr>
<tr>
<td class='confluenceTd'> use_manager_auth </td>
<td class='confluenceTd'> Share authentication with AMI over HTTP. </td>
<td class='confluenceTd'> Boolean </td>
<td class='confluenceTd'> no </td>
</tr>
</tbody></table>
</div>
<h4><a name="Asterisk12APIImprovements-%5Cusername%5C"></a>2.5.1.2. [username]</h4>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Parameter </th>
<th class='confluenceTh'> Description </th>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Default Value </th>
</tr>
<tr>
<td class='confluenceTd'> read_only </td>
<td class='confluenceTd'> When set to yes, user is only authorized for read-only requests. </td>
<td class='confluenceTd'> Boolean </td>
<td class='confluenceTd'> no </td>
</tr>
<tr>
<td class='confluenceTd'> crypt_password </td>
<td class='confluenceTd'> Method of encryption used on password. </td>
<td class='confluenceTd'> { crypt, plain } </td>
<td class='confluenceTd'> plain </td>
</tr>
<tr>
<td class='confluenceTd'> password </td>
<td class='confluenceTd'> Crypted or plaintext password for username. See <a href="#Asterisk12APIImprovements-HTTPAuthentication">authentication</a> below </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> n/a </td>
</tr>
</tbody></table>
</div>
<h3><a name="Asterisk12APIImprovements-stasiscore.conf"></a>2.5.2. stasis-core.conf</h3>
<p>Configuration for the Stasis Message Bus.</p>
<h4><a name="Asterisk12APIImprovements-%5Cthreadpool%5C"></a>2.5.2.1. [threadpool]</h4>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Parameter </th>
<th class='confluenceTh'> Description </th>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Default Value </th>
</tr>
<tr>
<td class='confluenceTd'> initial_size </td>
<td class='confluenceTd'> Initial size of the threadpool </td>
<td class='confluenceTd'> Integer </td>
<td class='confluenceTd'> 0 </td>
</tr>
<tr>
<td class='confluenceTd'> idle_timeout </td>
<td class='confluenceTd'> Number of seconds a thread should be idle before dying </td>
<td class='confluenceTd'> Integer (seconds) </td>
<td class='confluenceTd'> 20 </td>
</tr>
<tr>
<td class='confluenceTd'> max_size </td>
<td class='confluenceTd'> Maximum number of threads in the threadpool </td>
<td class='confluenceTd'> Integer </td>
<td class='confluenceTd'> 200 </td>
</tr>
</tbody></table>
</div>
<h3><a name="Asterisk12APIImprovements-RealTimeschemas"></a>2.5.3. RealTime schemas</h3>
<h2><a name="Asterisk12APIImprovements-APIs"></a>2.6. APIs</h2>
<h3><a name="Asterisk12APIImprovements-DialplanApplications"></a>2.6.1. Dialplan Applications</h3>
<p><b>Stasis</b> - direct a call to a Stasis application.</p>
<p><b>Arguments</b></p>
<ul>
<li><b>name</b> - Name of the application to direct the call to.</li>
<li><b>args</b> - List of arguments to pass to the application.</li>
</ul>
<p>The <tt>Stasis</tt> application is how a channel goes from the dialplan to a Stasis application. When a channel enters the <tt>Stasis</tt> application in the dialplan, a <a href="/wiki/display/AST/Asterisk+12+REST+Data+Models#Asterisk12RESTDataModels-StasisStart">StasisStart</a> event is sent to the application's associated WebSocket. The application can then control the channel using the <a href="/wiki/display/AST/Asterisk+12+RESTful+API" title="Asterisk 12 RESTful API">REST API</a>, returning the channel to the dialplan using the <a href="/wiki/display/AST/Asterisk+12+Channels+REST+API#Asterisk12ChannelsRESTAPI-continueInDialplan">/channels/{channelId}/continue</a> resource.</p>
<h3><a name="Asterisk12APIImprovements-RESTfulHTTPAPI"></a>2.6.2. RESTful HTTP API</h3>
<p>As <a href="#Asterisk12APIImprovements-resstasishttp">detailed below</a>, Stasis will expose a RESTful HTTP API for third party call control. This API should be documented using <a href="http://swagger.wordnik.com/" class="external-link" rel="nofollow">Swagger</a>, which allows for not only the generation of usable, interactive documentation, but also allows for the generation of server stubs, reducing a lot of the tediousness required in implementing a web application in C.</p>
<p>See the <a href="/wiki/display/AST/Asterisk+12+RESTful+API" title="Asterisk 12 RESTful API">Asterisk 12 RESTful API</a> page for full descriptions of the proposed RESTful API, including URL's, supported methods, and the schema of the returned resources.</p>
<p>The Swagger API documentation lives in the <tt>rest-api/</tt> directory in source. The generated code may be regenerated using <tt>make stasis-stubs</tt>, and requires Python and <a href="https://github.com/defunkt/pystache" class="external-link" rel="nofollow">pystache</a> to be installed. We also have a <a href="https://github.com/leedm777/swagger-codegen/tree/confluence-generator" class="external-link" rel="nofollow">branch of the swagger-codegen</a> which we use to generate <a href="/wiki/display/AST/Asterisk+12+RESTful+API" title="Asterisk 12 RESTful API">the documentation mentioned above</a>.</p>
<p>A project is underway to write an <a href="/wiki/display/AST/Asterisk+Client+Library+Generator" title="Asterisk Client Library Generator">Asterisk Client Library Generator</a> which will be capable of producing comprehensive client libraries in several languages. The generator uses the Swagger resource files included in Asterisk to generate the libraries.</p>
<p>Message formats will initially be in JSON, but care will be taken with message design so that adding support for XML will be straightforward.</p>
<h4><a name="Asterisk12APIImprovements-ErrorResponses"></a>2.6.2.1. Error Responses</h4>
<p>The RESTful API will follow HTTP conventions for <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" class="external-link" rel="nofollow">HTTP return codes</a>. If you try to access a channel that does not exist, you will get a 404 Not Found. If you try to play audio on a channel that isn't currently in a Stasis application, you will get a 409 Conflict. If Asterisk encounters an unexpected error, you will get a 500 Internal Server Error.</p>
<p>In addition to the HTTP error code, the response body will be a JSON doc (or XML, when we support it) describing the error in further detail.</p>
<h4><a name="Asterisk12APIImprovements-WebSocketEvents"></a>2.6.2.2. WebSocket Events</h4>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Originally it was thought that the WebSocket would also accept commands for managing subscriptions, applications, etc. It turned out to complicate a lot more than it simplified, so it made more sense to make the WebSocket simply an asynchronous event channel from Asterisk to the Stasis-HTTP client.</td></tr></table></div>
<p>In addition to responding to commands from the application, Stasis-HTTP will also need to asynchronously send events to the application, notifying the application of new channels, state changes, etc.</p>
<p>While it's not strictly a part of the RESTful API, it is treated as if it were. The WebSocket API is <a href="/wiki/display/AST/Asterisk+12+Events+REST+API" title="Asterisk 12 Events REST API">documented using Swagger</a>, and its URL will be <tt>/stasis/events</tt>, alongside the RESTful URL's. The events that will be sent on the WebSocket are document in the <a href="/wiki/display/AST/Asterisk+12+REST+Data+Models#Asterisk12RESTDataModels-Event">RESTfu API data models</a>.</p>
<h4><a name="Asterisk12APIImprovements-HTTPAuthentication"></a>2.6.2.3. HTTP Authentication</h4>
<p>Usernames and passwords for Stasis-HTTP are configured in stasis-http.conf (<a href="#Asterisk12APIImprovements-stasishttp.conf">see above</a>).</p>
<p>If a user is configured without a password, their username is treated as an API key. They can authenticate to Stasis-HTTP by simply passing their API key along using the <tt>api_key=</tt> request parameter.</p>
<p>If the user is configured with a password, they must authenticate using HTTP Basic authentication.</p>
<p>The password may be stored as plaintext, or can be stored using <a href="http://man7.org/linux/man-pages/man3/crypt.3.html" class="external-link" rel="nofollow">crypt(3)</a>. A crypted password can be generated using the <tt>mkpasswd -m sha-512</tt> command.</p>
<h1><a name="Asterisk12APIImprovements-Design"></a>3. Design </h1>
<p><a name="Asterisk12APIImprovements-messagebus"></a> </p>
<h2><a name="Asterisk12APIImprovements-%7B%7Bstasis.c%7D%7DStasisMessageBus"></a>3.1. <tt>stasis.c</tt> - Stasis Message Bus </h2>
<p><b>Header</b>: <tt>asterisk/stasis.h</tt> </p>
<p>The <a href="/wiki/display/AST/Stasis+Message+Bus" title="Stasis Message Bus">Stasis Message Bus</a> is how message producers and consumers are decoupled within the new API work. </p>
<p>Please see the <a href="http://doxygen.asterisk.org/trunk/stasis.html" class="external-link" rel="nofollow">API docs</a> and the <a href="/wiki/display/AST/Stasis+Message+Bus" title="Stasis Message Bus">wiki page</a> for further details. </p>
<h2><a name="Asterisk12APIImprovements-%7B%7Bresstasis.c%7D%7DStasisApplicationAPI"></a>3.2. <tt>res_stasis.c</tt> - Stasis Application API </h2>
<p><b>Header</b>: <tt>asterisk/stasis_app.h</tt> </p>
<p>High level application API's for Asterisk. The <a href="#Asterisk12APIImprovements-messagebus">Message Bus</a> provides a read-only view into Asterisk. This API gives you high level manipulation. The functions in this API should correspond roughly one-to-one to the sorts of methods you would put into an external API. </p>
<p>Please see the <a href="http://doxygen.asterisk.org/trunk/d8/d9c/stasis__app_8h.html" class="external-link" rel="nofollow">API docs</a> for further details.. </p>
<h2><a name="Asterisk12APIImprovements-%7B%7Bappstasis.c%7D%7DStasisDialplanApplication"></a>3.3. <tt>app_stasis.c</tt> - Stasis Dialplan Application </h2>
<p><b>Application</b>: Stasis </p>
<p>The <tt>app_stasis.so</tt> module simply exports the <tt>res_stasis.so</tt> functionality as a dialplan application. This allows you to send channels to a Stasis application from within the dialplan. </p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: plain; gutter: false">; Send channel to the 'Queue' application, with the args 'enqueue,sales'
exten => 7001,1,Stasis(Queue,enqueue,sales)</pre>
</div></div>
<h2><a name="Asterisk12APIImprovements-%7B%7Bstasis%5C.c%7D%7D"></a>3.4. <tt>stasis_{channels,bridges,endpoints}.c</tt> </h2>
<p><b>Headers</b>: <tt>stasis_{channels,bridges,endpoints}.h</tt> </p>
<p>Channels, endpoints and bridges will have their own Stasis topics and messages for publishing state and event messages about themselves. Each object also has a <em>snapshot</em>, which is a immutable struct representing the state of the underlying object at a particular point in time. </p>
<p>Each object has its own topic, to which it posts snapshots and messages regarding events that happen to that object. These messages are all forwarded to an aggregation topic (<tt>ast_{channel,endpoint,bridge}_topic_all</tt>), which is cached by a caching topic (<tt>ast_{channel,endpoint,bridge}_topic_all_cached</tt>). </p>
<p>The aggregation and caching topics allow for components that need to monitor the overall state of the system (such as Manager). The caching topics allows components to query for the most recent snapshot of an object without querying the actual object itself. The reduces contention on the object itself, and reduces the opportunities for deadlock. </p>
<p>See the <a href="http://doxygen.asterisk.org/trunk/df/deb/group__StasisTopicsAndMessages.html" class="external-link" rel="nofollow">API docs</a> for further details. </p>
<h2><a name="Asterisk12APIImprovements-%7B%7Bmanager%5C.c%7D%7DExistingcomponentrefactoring."></a>3.5. <tt>manager_{channels,bridges,endpoints}.c</tt> - Existing component refactoring. </h2>
<p>Existing Manager events and CLI commands can (and should) be refactored to receive events from the appropriate aggregator topics, and retrieve state from the cache topics. </p>
<p>The topics and messages for the main components of Asterisk are defined in <tt>main/stasis_{channel,endpoint,bridge}.c</tt>. The refactored Manager code will be implemented in <tt>main/manager_{channel,endpoint,bridge}.c</tt>. </p>
<h2><a name="Asterisk12APIImprovements-StasisRESTfulAPI"></a>3.6. Stasis RESTful API </h2>
<p><b>API docs</b>: <tt>rest-api</tt> </p>
<p>The RESTful Stasis HTTP implementation is broken down into several components. Much of the boiler plate code declaring routes and parsing parameters is done by code generated by the API docs. The generated code can be regenerated by running <tt>make stasis-stubs</tt>. </p>
<h3><a name="Asterisk12APIImprovements-%7B%7Bresstasishttp.c%7D%7DRequesthandlingandrouting"></a>3.6.1. <tt>res_stasis_http.c</tt> - Request handling and routing </h3>
<p><b>Header</b>: <tt>asterisk/stasis_http.h</tt> </p>
<p>The <tt>res_stasis_http.so</tt> module has the common code for handling and routing requests. HTTP resource modules register themselves with the RESTful API by using the <tt>stasis_http_add_handler()</tt> and <tt>stasis_http_remove_handler()</tt> functions. </p>
<h3><a name="Asterisk12APIImprovements-%7B%7Bresstasishttp%5C.c%7D%7D%28generated%29"></a>3.6.2. <tt>res_stasis_http_{resource}.c</tt> (generated) </h3>
<p>The structures declaring the routing for requests for a specific resource, and callbacks for parsing request arguments for the request. </p>
<h3><a name="Asterisk12APIImprovements-%7B%7Bstasishttp%2Fresource%5C.c%7D%7D"></a>3.6.3. <tt>stasis_http/resource_{resource}.c</tt> </h3>
<p><b>Header</b>: <tt>stasis_http/resource_{resource}.h</tt> (generated) </p>
<p>Implementation code for RESTful HTTP requests. The bulk of this code should be in consuming the request and producing the response. The bulk of the logic to carry out the request belongs in <tt>res_stasis.so</tt>, or in the underlying component. By keeping the HTTP modules free of business logic, we give ourselves a better shot at implementing other API bindings in a way that the different interfaces actually act consistently.</p>
<h1><a name="Asterisk12APIImprovements-TestPlan"></a>4. Test Plan</h1>
<p>Each controller in the RESTful API should have at least one integration test validating that function. Many will have multiple tests to validate failure conditions (originate failed, etc.).</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Test </th>
<th class='confluenceTh'> Level </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> stasis_obj_to_json </td>
<td class='confluenceTd'> Unit </td>
<td class='confluenceTd'> Tests Stasis object to JSON codec </td>
</tr>
<tr>
<td class='confluenceTd'> stasis_obj_to_xml </td>
<td class='confluenceTd'> Unit </td>
<td class='confluenceTd'> Tests Stasis object to XML codec </td>
</tr>
</tbody></table>
</div>
<h1><a name="Asterisk12APIImprovements-ProjectPlanning"></a>5. Project Planning</h1>
<h2><a name="Asterisk12APIImprovements-JIRAIssues"></a>5.1. JIRA Issues</h2>
<p>
<table cellspacing="0" class="grid" style="width: 100%">
<tr>
<th colspan="11" style="text-align: left; ">
<a rel="nofollow" href="https://issues.asterisk.org/jira/secure/IssueNavigator.jspa?requestId=11923&tempMax=1000">JIRA Issues</a> (16 issues) </th>
</tr>
<tr>
<th style="text-align: left; text-transform: capitalize;">Type</th>
<th style="text-align: left; text-transform: capitalize;">Key</th>
<th style="text-align: left; text-transform: capitalize;">Summary</th>
<th style="text-align: left; text-transform: capitalize;">Assignee</th>
<th style="text-align: left; text-transform: capitalize;">Reporter</th>
<th style="text-align: left; text-transform: capitalize;">Priority</th>
<th style="text-align: left; text-transform: capitalize;">Status</th>
<th style="text-align: left; text-transform: capitalize;">Resolution</th>
<th style="text-align: left; text-transform: capitalize;">Created</th>
<th style="text-align: left; text-transform: capitalize;">Updated</th>
<th style="text-align: left; text-transform: capitalize;">Due</th>
</tr>
<tr class="rowNormal">
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21421"><img src="https://issues.asterisk.org/jira/images/icons/issuetypes/newfeature.png" alt="New Feature" border="0" /></a>
</td>
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21421">ASTERISK-21421</a>
</td>
<td >
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21421">API Improvements: build out the concept of an endpoint in Stasis-Core</a>
</td>
<td nowrap="true">
David M. Lee
</td>
<td nowrap="true">
Matt Jordan
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/priorities/major.png" alt="Major" border="0" />
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/statuses/open.png" alt="" border="0" /> Open
</td>
<td nowrap="true">
<font color="990000">Unresolved</font>
</td>
<td nowrap="true">
Apr 12, 2013
</td>
<td nowrap="true">
Apr 16, 2013
</td>
<td nowrap="true">
</td>
</tr>
<tr class="rowAlternate">
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21283"><img src="https://issues.asterisk.org/jira/images/icons/issuetypes/newfeature.png" alt="New Feature" border="0" /></a>
</td>
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21283">ASTERISK-21283</a>
</td>
<td >
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21283">Implement stasis-http POST /api/channels/{channelId}/play</a>
</td>
<td nowrap="true">
Unassigned
</td>
<td nowrap="true">
David M. Lee
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/priorities/major.png" alt="Major" border="0" />
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/statuses/open.png" alt="" border="0" /> Open
</td>
<td nowrap="true">
<font color="990000">Unresolved</font>
</td>
<td nowrap="true">
Mar 15, 2013
</td>
<td nowrap="true">
Mar 15, 2013
</td>
<td nowrap="true">
</td>
</tr>
<tr class="rowNormal">
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21282"><img src="https://issues.asterisk.org/jira/images/icons/issuetypes/newfeature.png" alt="New Feature" border="0" /></a>
</td>
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21282">ASTERISK-21282</a>
</td>
<td >
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21282">Add DTMF events to the stasis-http WebSocket</a>
</td>
<td nowrap="true">
David M. Lee
</td>
<td nowrap="true">
David M. Lee
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/priorities/major.png" alt="Major" border="0" />
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/statuses/open.png" alt="" border="0" /> Open
</td>
<td nowrap="true">
<font color="990000">Unresolved</font>
</td>
<td nowrap="true">
Mar 15, 2013
</td>
<td nowrap="true">
Apr 03, 2013
</td>
<td nowrap="true">
</td>
</tr>
<tr class="rowAlternate">
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21281"><img src="https://issues.asterisk.org/jira/images/icons/issuetypes/improvement.png" alt="Improvement" border="0" /></a>
</td>
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21281">ASTERISK-21281</a>
</td>
<td >
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21281">stasis-http: Create Confluence swagger-codegen templates</a>
</td>
<td nowrap="true">
David M. Lee
</td>
<td nowrap="true">
David M. Lee
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/priorities/major.png" alt="Major" border="0" />
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/statuses/open.png" alt="" border="0" /> Open
</td>
<td nowrap="true">
<font color="990000">Unresolved</font>
</td>
<td nowrap="true">
Mar 15, 2013
</td>
<td nowrap="true">
Apr 03, 2013
</td>
<td nowrap="true">
</td>
</tr>
<tr class="rowNormal">
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21280"><img src="https://issues.asterisk.org/jira/images/icons/issuetypes/improvement.png" alt="Improvement" border="0" /></a>
</td>
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21280">ASTERISK-21280</a>
</td>
<td >
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21280">Basic configuration for stasis-core</a>
</td>
<td nowrap="true">
Unassigned
</td>
<td nowrap="true">
David M. Lee
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/priorities/major.png" alt="Major" border="0" />
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/statuses/open.png" alt="" border="0" /> Open
</td>
<td nowrap="true">
<font color="990000">Unresolved</font>
</td>
<td nowrap="true">
Mar 15, 2013
</td>
<td nowrap="true">
Mar 15, 2013
</td>
<td nowrap="true">
</td>
</tr>
<tr class="rowAlternate">
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21279"><img src="https://issues.asterisk.org/jira/images/icons/issuetypes/improvement.png" alt="Improvement" border="0" /></a>
</td>
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21279">ASTERISK-21279</a>
</td>
<td >
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21279">Allow WebSocket connections on URL's other than /ws</a>
</td>
<td nowrap="true">
David M. Lee
</td>
<td nowrap="true">
David M. Lee
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/priorities/major.png" alt="Major" border="0" />
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/statuses/open.png" alt="" border="0" /> Open
</td>
<td nowrap="true">
<font color="990000">Unresolved</font>
</td>
<td nowrap="true">
Mar 15, 2013
</td>
<td nowrap="true">
Apr 15, 2013
</td>
<td nowrap="true">
</td>
</tr>
<tr class="rowNormal">
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21278"><img src="https://issues.asterisk.org/jira/images/icons/issuetypes/newfeature.png" alt="New Feature" border="0" /></a>
</td>
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21278">ASTERISK-21278</a>
</td>
<td >
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21278">stasis-http Cross-Origin configuration</a>
</td>
<td nowrap="true">
Unassigned
</td>
<td nowrap="true">
David M. Lee
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/priorities/major.png" alt="Major" border="0" />
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/statuses/open.png" alt="" border="0" /> Open
</td>
<td nowrap="true">
<font color="990000">Unresolved</font>
</td>
<td nowrap="true">
Mar 15, 2013
</td>
<td nowrap="true">
Mar 15, 2013
</td>
<td nowrap="true">
</td>
</tr>
<tr class="rowAlternate">
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21277"><img src="https://issues.asterisk.org/jira/images/icons/issuetypes/newfeature.png" alt="New Feature" border="0" /></a>
</td>
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21277">ASTERISK-21277</a>
</td>
<td >
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21277">stasis-http authentication</a>
</td>
<td nowrap="true">
Unassigned
</td>
<td nowrap="true">
David M. Lee
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/priorities/major.png" alt="Major" border="0" />
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/statuses/open.png" alt="" border="0" /> Open
</td>
<td nowrap="true">
<font color="990000">Unresolved</font>
</td>
<td nowrap="true">
Mar 15, 2013
</td>
<td nowrap="true">
Mar 15, 2013
</td>
<td nowrap="true">
</td>
</tr>
<tr class="rowNormal">
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21196"><img src="https://issues.asterisk.org/jira/images/icons/issuetypes/improvement.png" alt="Improvement" border="0" /></a>
</td>
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21196">ASTERISK-21196</a>
</td>
<td >
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21196">Refactor CDRs onto Stasis-Core to handle changes in bridging behavior</a>
</td>
<td nowrap="true">
Matt Jordan
</td>
<td nowrap="true">
Matt Jordan
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/priorities/major.png" alt="Major" border="0" />
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/statuses/inprogress.png" alt="" border="0" /> In Progress
</td>
<td nowrap="true">
<font color="990000">Unresolved</font>
</td>
<td nowrap="true">
Mar 01, 2013
</td>
<td nowrap="true">
Mar 06, 2013
</td>
<td nowrap="true">
</td>
</tr>
<tr class="rowAlternate">
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21182"><img src="https://issues.asterisk.org/jira/images/icons/issuetypes/newfeature.png" alt="New Feature" border="0" /></a>
</td>
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21182">ASTERISK-21182</a>
</td>
<td >
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21182">Create documentation/specification for expected Stasis HTTP events</a>
</td>
<td nowrap="true">
David M. Lee
</td>
<td nowrap="true">
Matt Jordan
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/priorities/major.png" alt="Major" border="0" />
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/statuses/open.png" alt="" border="0" /> Open
</td>
<td nowrap="true">
<font color="990000">Unresolved</font>
</td>
<td nowrap="true">
Feb 27, 2013
</td>
<td nowrap="true">
Apr 03, 2013
</td>
<td nowrap="true">
</td>
</tr>
<tr class="rowNormal">
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21180"><img src="https://issues.asterisk.org/jira/images/icons/issuetypes/newfeature.png" alt="New Feature" border="0" /></a>
</td>
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21180">ASTERISK-21180</a>
</td>
<td >
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21180">Implement channel state events for Stasis HTTP</a>
</td>
<td nowrap="true">
Kinsey Moore
</td>
<td nowrap="true">
Matt Jordan
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/priorities/major.png" alt="Major" border="0" />
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/statuses/open.png" alt="" border="0" /> Open
</td>
<td nowrap="true">
<font color="990000">Unresolved</font>
</td>
<td nowrap="true">
Feb 27, 2013
</td>
<td nowrap="true">
Apr 01, 2013
</td>
<td nowrap="true">
</td>
</tr>
<tr class="rowAlternate">
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21103"><img src="https://issues.asterisk.org/jira/images/icons/issuetypes/improvement.png" alt="Improvement" border="0" /></a>
</td>
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21103">ASTERISK-21103</a>
</td>
<td >
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21103">Stasis Core - Refactor the other event types onto the Stasis Core message bus</a>
</td>
<td nowrap="true">
Unassigned
</td>
<td nowrap="true">
Matt Jordan
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/priorities/major.png" alt="Major" border="0" />
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/statuses/open.png" alt="" border="0" /> Open
</td>
<td nowrap="true">
<font color="990000">Unresolved</font>
</td>
<td nowrap="true">
Feb 14, 2013
</td>
<td nowrap="true">
Feb 14, 2013
</td>
<td nowrap="true">
</td>
</tr>
<tr class="rowNormal">
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21102"><img src="https://issues.asterisk.org/jira/images/icons/issuetypes/bug.png" alt="Bug" border="0" /></a>
</td>
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21102">ASTERISK-21102</a>
</td>
<td >
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21102">Stasis Core - Refactor Presence State support</a>
</td>
<td nowrap="true">
Kinsey Moore
</td>
<td nowrap="true">
Matt Jordan
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/priorities/major.png" alt="Major" border="0" />
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/statuses/open.png" alt="" border="0" /> Open
</td>
<td nowrap="true">
<font color="990000">Unresolved</font>
</td>
<td nowrap="true">
Feb 14, 2013
</td>
<td nowrap="true">
Mar 22, 2013
</td>
<td nowrap="true">
</td>
</tr>
<tr class="rowAlternate">
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21101"><img src="https://issues.asterisk.org/jira/images/icons/issuetypes/improvement.png" alt="Improvement" border="0" /></a>
</td>
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21101">ASTERISK-21101</a>
</td>
<td >
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21101">Stasis Core - Refactor Device State support</a>
</td>
<td nowrap="true">
Kinsey Moore
</td>
<td nowrap="true">
Matt Jordan
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/priorities/major.png" alt="Major" border="0" />
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/statuses/inprogress.png" alt="" border="0" /> In Progress
</td>
<td nowrap="true">
<font color="990000">Unresolved</font>
</td>
<td nowrap="true">
Feb 14, 2013
</td>
<td nowrap="true">
Mar 15, 2013
</td>
<td nowrap="true">
</td>
</tr>
<tr class="rowNormal">
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21028"><img src="https://issues.asterisk.org/jira/images/icons/issuetypes/newfeature.png" alt="New Feature" border="0" /></a>
</td>
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21028">ASTERISK-21028</a>
</td>
<td >
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-21028">Implement stasis-http POST /api/channels/{channelId}/continue</a>
</td>
<td nowrap="true">
David M. Lee
</td>
<td nowrap="true">
David M. Lee
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/priorities/major.png" alt="Major" border="0" />
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/statuses/open.png" alt="" border="0" /> Open
</td>
<td nowrap="true">
<font color="990000">Unresolved</font>
</td>
<td nowrap="true">
Feb 01, 2013
</td>
<td nowrap="true">
Mar 14, 2013
</td>
<td nowrap="true">
</td>
</tr>
<tr class="rowAlternate">
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-20891"><img src="https://issues.asterisk.org/jira/images/icons/issuetypes/newfeature.png" alt="New Feature" border="0" /></a>
</td>
<td nowrap="true">
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-20891">ASTERISK-20891</a>
</td>
<td >
<a href="https://issues.asterisk.org/jira/browse/ASTERISK-20891">Flesh out RESTful API's</a>
</td>
<td nowrap="true">
David M. Lee
</td>
<td nowrap="true">
David M. Lee
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/priorities/major.png" alt="Major" border="0" />
</td>
<td nowrap="true">
<img src="https://issues.asterisk.org/jira/images/icons/statuses/open.png" alt="" border="0" /> Open
</td>
<td nowrap="true">
<font color="990000">Unresolved</font>
</td>
<td nowrap="true">
Jan 04, 2013
</td>
<td nowrap="true">
Jan 07, 2013
</td>
<td nowrap="true">
</td>
</tr>
</table>
</p>
<h2><a name="Asterisk12APIImprovements-Contributors"></a>5.2. Contributors</h2>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Name </th>
<th class='confluenceTh'> E-mail Address </th>
</tr>
<tr>
<td class='confluenceTd'> <a href="/wiki/display/~dlee" class="confluence-userlink" data-username="dlee" >David M. Lee</a> </td>
<td class='confluenceTd'> dlee@digium.com </td>
</tr>
</tbody></table>
</div>
<h1><a name="Asterisk12APIImprovements-ReferenceInformation"></a>6. Reference Information</h1>
<ul>
<li>Stable identifier for channels:
<ul>
<li><a href="/wiki/display/~dlee/Stable+Identifiers+for+Asterisk" title="Stable Identifiers for Asterisk">Stable Identifiers for Asterisk</a></li>
<li><a href="http://lists.digium.com/pipermail/asterisk-dev/2009-May/038430.html" class="external-link" rel="nofollow">http://lists.digium.com/pipermail/asterisk-dev/2009-May/038430.html</a></li>
<li><a href="http://lists.digium.com/pipermail/asterisk-dev/2010-June/044754.html" class="external-link" rel="nofollow">http://lists.digium.com/pipermail/asterisk-dev/2010-June/044754.html</a></li>
<li><a href="https://reviewboard.asterisk.org/r/760/" class="external-link" rel="nofollow">https://reviewboard.asterisk.org/r/760/</a></li>
</ul>
</li>
<li>Stasis API:
<ul>
<li><a href="http://lists.digium.com/pipermail/asterisk-dev/2012-November/057814.html" class="external-link" rel="nofollow">http://lists.digium.com/pipermail/asterisk-dev/2012-November/057814.html</a>
<ul>
<li>Thread continues here: <a href="http://lists.digium.com/pipermail/asterisk-dev/2012-December/057853.html" class="external-link" rel="nofollow">http://lists.digium.com/pipermail/asterisk-dev/2012-December/057853.html</a></li>
</ul>
</li>
<li><a href="http://lists.digium.com/pipermail/asterisk-dev/2012-December/057893.html" class="external-link" rel="nofollow">http://lists.digium.com/pipermail/asterisk-dev/2012-December/057893.html</a></li>
</ul>
</li>
</ul>
<h1><a name="Asterisk12APIImprovements-Footnotes"></a>7. Footnotes</h1>
<ul>
<li><a name="Asterisk12APIImprovements-badname"></a> While it may stand for "Some Thought Actually Spent In Specification", suggestions for a better name are welcome.</li>
</ul>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://wiki.asterisk.org/wiki/users/removespacenotification.action?spaceKey=AST">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://wiki.asterisk.org/wiki/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/AST/Asterisk+12+API+Improvements">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=21464586&revisedVersion=13&originalVersion=12">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/Asterisk+12+API+Improvements?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>