No subject


Fri Jun 28 13:27:35 CDT 2013


y toolkit." However, whether or not we are PBX-centric has implication=
s for the API.

Currently, Asterisk leans more toward being a toolkit than a PBX. There is =
a very loose coupling between extensions and endpoints, as is typically def=
ined 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 depe=
nding upon your application, and being able to be applied to a variety of a=
pplications is what has made Asterisk so successful.

However, the primary application Asterisk is applied to is being a PBX. It =
is important that developers writing PBX applications aren't bogged down wi=
th general telephony toolkit details.

So while the PBX use cases are important, they should not undermine the gen=
eral purpose toolkit use cases. Largely, this will influence default values=
 and conventions of the API.

h3. Convention over Configuration

Continuing on with the theme of PBX vs. Toolkit, the API should adopt an ap=
proach of convention over configuration: reasonable defaults should be used=
 wherever possible. Configuration should be possible, allowing users to spe=
cify their own values in place of these defaults.

h2. Configuration

h3. stasis-http.conf

Configuration for the HTTP binding for Stasis.

h4. \[general\]

|| Parameter || Description || Type || Default Value ||
| enabled | Turns Stasis HTTP binding on or off \\
HTTP server must be enabled in http.conf for this to take effect | Boolean =
| yes |
| pretty | When set to yes, responses from stasis-http are formatted to be =
human readable | Boolean | no |
| allowed_origins | Comma separated list of allowed origins, for Cross-Orig=
in Resource Sharing. May be set to {{\*}} to allow all origins. | Comma sep=
arated strings | |
| use_manager_auth | Share authentication with AMI over HTTP. | Boolean | n=
o |

h4. \[username\]

|| Parameter || Description || Type || Default Value ||
| read_only | When set to yes, user is only authorized for read-only reques=
ts. | Boolean | no |
| crypt_password | Method of encryption used on password. | \{ crypt, plain=
 \} | plain |
| password | Crypted or plaintext password for username. See [authenticatio=
n|#HTTP Authentication] below | String | n/a |

h3. stasis-core.conf

Configuration for the Stasis Message Bus.

h4. \[threadpool\]

|| Parameter || Description || Type || Default Value ||
| initial_size | Initial size of the threadpool | Integer | 0 |
| idle_timeout | Number of seconds a thread should be idle before dying | I=
nteger (seconds) | 20 |
| max_size | Maximum number of threads in the threadpool | Integer | 200 |

h3. RealTime schemas

h2. APIs

h3. Dialplan Applications

*Stasis* \- direct a call to a Stasis application.

*Arguments*
* *name* \- Name of the application to direct the call to.
* *args* \- List of arguments to pass to the application.

The  {{Stasis}} application is how a channel goes from the dialplan to a St=
asis application. When a channel enters the {{Stasis}} application in the d=
ialplan, a [StasisStart|AST:Asterisk 12 REST Data Models#StasisStart] event=
 is sent to the application's associated WebSocket. The application can the=
n control the channel using the [REST API|Asterisk 12 RESTful API], returni=
ng the channel to the dialplan using the [/channels/\{channelId\}/continue|=
AST:Asterisk 12 Channels REST API#continueInDialplan] resource.

h3. RESTful HTTP API

As [detailed below|#res_stasis_http], Stasis will expose a RESTful HTTP API=
 for third party call control. This API should be documented using [Swagger=
|http://swagger.wordnik.com/], which allows for not only the generation of =
usable, interactive documentation, but also allows for the generation of se=
rver stubs, reducing a lot of the tediousness required in implementing a we=
b application in C.

See the [Asterisk 12 RESTful API] page for full descriptions of the propose=
d RESTful API, including URL's, supported methods, and the schema of the re=
turned resources.

The Swagger API documentation lives in the {{rest-api/}} directory in sourc=
e. The generated code may be regenerated using {{make stasis-stubs}}, and r=
equires Python and [pystache|https://github.com/defunkt/pystache] to be ins=
talled. <span class=3D"diff-html-removed" id=3D"removed-diff-0" style=3D"fo=
nt-size: 100%; background-color: #ffe7e7; text-decoration: line-through;">W=
e</span><span class=3D"diff-html-added" id=3D"added-diff-0" style=3D"font-s=
ize: 100%; background-color: #ddfade;">In</span> <span class=3D"diff-html-r=
emoved" id=3D"removed-diff-1" style=3D"font-size: 100%; background-color: #=
ffe7e7; text-decoration: line-through;">also</span><span class=3D"diff-html=
-added" id=3D"added-diff-1" style=3D"font-size: 100%; background-color: #dd=
fade;">addition</span> <span class=3D"diff-html-removed" id=3D"removed-diff=
-2" style=3D"font-size: 100%; background-color: #ffe7e7; text-decoration: l=
ine-through;">have</span><span class=3D"diff-html-added" id=3D"added-diff-2=
" style=3D"font-size: 100%; background-color: #ddfade;">to</span> <span cla=
ss=3D"diff-html-added" id=3D"added-diff-3" style=3D"font-size: 100%; backgr=
ound-color: #ddfade;">generating </span>a <span class=3D"diff-html-removed"=
 id=3D"removed-diff-3" style=3D"font-size: 100%; background-color: #ffe7e7;=
 text-decoration: line-through;">[branch</span><span class=3D"diff-html-add=
ed" id=3D"added-diff-4" style=3D"font-size: 100%; background-color: #ddfade=
;">ton</span> of <span class=3D"diff-html-removed" id=3D"removed-diff-4" st=
yle=3D"font-size: 100%; background-color: #ffe7e7; text-decoration: line-th=
rough;">the swagger-codegen|https://github.com/leedm777/swagger-codegen/tre=
e/confluence-generator] which we use to generate </span><span class=3D"diff=
-html-added" id=3D"added-diff-5" style=3D"font-size: 100%; background-color=
: #ddfade;">boilerplate code for implementing the API, it also generates </=
span>[the documentation mentioned above|AST:Asterisk 12 RESTful API].

A project is underway to write an [Asterisk Client Library Generator] which=
 will be capable of producing comprehensive client libraries in several lan=
guages.  The generator uses the Swagger resource files included in Asterisk=
 to generate the libraries.

Message formats will initially be in JSON, but care will be taken with mess=
age design so that adding support for XML will be straightforward.

h4. Error Responses

The RESTful API will follow HTTP conventions for [HTTP return codes|http://=
www.w3.org/Protocols/rfc2616/rfc2616-sec10.html]. If you try to access a ch=
annel 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 ge=
t a 500 Internal Server Error.

In addition to the HTTP error code, the response body will be a JSON doc (o=
r XML, when we support it) describing the error in further detail.

h4. WebSocket Events

{note}
Originally it was thought that the WebSocket would also accept commands for=
 managing subscriptions, applications, etc. It turned out to complicate a l=
ot more than it simplified, so it made more sense to make the WebSocket sim=
ply an asynchronous event channel from Asterisk to the Stasis-HTTP client.
{note}

In addition to responding to commands from the application, Stasis-HTTP wil=
l also need to asynchronously send events to the application, notifying the=
 application of new channels, state changes, etc.

While it's not strictly a part of the RESTful API, it is treated as if it w=
ere. The WebSocket API is [documented using Swagger|AST:Asterisk 12 Events =
REST API], and its URL will be {{/stasis/events}}, alongside the RESTful UR=
L's. The events that will be sent on the WebSocket are document in the [RES=
Tfu API data models|AST:Asterisk 12 REST Data Models#Event].

h4. HTTP Authentication

Usernames and passwords for Stasis-HTTP are configured in stasis-http.conf =
([see above|#stasis-http.conf]).

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 {{api_key=3D}} request parameter.

If the user is configured with a password, they must authenticate using HTT=
P Basic authentication.

The password may be stored as plaintext, or can be stored using [crypt(3)|h=
ttp://man7.org/linux/man-pages/man3/crypt.3.html]. A crypted password can b=
e generated using the {{mkpasswd -m sha-512}} command.

h1. Design

h2. Pretty Picture

{gliffy:name=3DPrettyPicture|align=3Dleft|size=3DL|version=3D1}

{anchor:message-bus}
h2. {{stasis.c}} - Stasis Message Bus

*Header*: {{asterisk/stasis.h}}

The [Stasis Message Bus|AST:Stasis Message Bus] is how message producers an=
d consumers are decoupled within the new API work.

Please see the [API docs|http://doxygen.asterisk.org/trunk/stasis.html] and=
 the [wiki page|AST:Stasis Message Bus] for further details.

h2. {{res_stasis.c}} - Stasis Application API

*Header*: {{asterisk/stasis_app.h}}

High level application API's for Asterisk. The [Message Bus|#message-bus] p=
rovides a read-only view into Asterisk. This API gives you high level manip=
ulation. The functions in this API should correspond roughly one-to-one to =
the sorts of methods you would put into an external API.

Please see the [API docs|http://doxygen.asterisk.org/trunk/d8/d9c/stasis__a=
pp_8h.html] for further details..

h2. {{app_stasis.c}} - Stasis Dialplan Application

*Application*: Stasis

The {{app\_stasis.so}} module simply exports the {{res\_stasis.so}} functio=
nality as a dialplan application. This allows you to send channels to a Sta=
sis application from within the dialplan.

{code:none}
; Send channel to the 'Queue' application, with the args 'enqueue,sales'
exten =3D&gt; 7001,1,Stasis(Queue,enqueue,sales)
{code}

h2. {{stasis_\{channels,bridges,endpoints\}.c}}

*Headers*: {{stasis_\{channels,bridges,endpoints\}.h}}

Channels, endpoints and bridges will have their own Stasis topics and messa=
ges for publishing state and event messages about themselves. Each object a=
lso has a _snapshot_, which is a immutable struct representing the state of=
 the underlying object at a particular point in time.

Each object has its own topic, to which it posts snapshots and messages reg=
arding 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}\_topi=
c\_all\_cached}}).

The aggregation and caching topics allow for components that need to monito=
r the overall state of the system (such as Manager). The caching topics all=
ows components to query for the most recent snapshot of an object without q=
uerying the actual object itself. The reduces contention on the object itse=
lf, and reduces the opportunities for deadlock.

See the [API docs|http://doxygen.asterisk.org/trunk/df/deb/group__StasisTop=
icsAndMessages.html] for further details.

h2. {{manager_\{channels,bridges,endpoints\}.c}} - Existing component refac=
toring.

Existing Manager events and CLI commands can (and should) be refactored to =
receive events from the appropriate aggregator topics, and retrieve state f=
rom the cache topics.

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}}.

h2. Stasis RESTful API

*API docs*: {{rest-api}}

The RESTful Stasis HTTP implementation is broken down into several componen=
ts. Much of the boiler plate code declaring routes and parsing parameters i=
s done by code generated by the API docs. The generated code can be regener=
ated by running {{make stasis-stubs}}.

h3. {{res_stasis_http.c}} - Request handling and routing

*Header*: {{asterisk/stasis\_http.h}}

The {{res\_stasis\_http.so}} module has the common code for handling and ro=
uting requests. HTTP resource modules register themselves with the RESTful =
API by using the {{stasis_http_add_handler()}} and {{stasis_http_remove_han=
dler()}} functions.

h3. {{res_stasis_http_\{resource\}.c}} (generated)

The structures declaring the routing for requests for a specific resource, =
and callbacks for parsing request arguments for the request.

h3. {{stasis_http/resource_\{resource\}.c}}

*Header*: {{stasis_http/resource_\{resource\}.h}} (generated)

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 lo=
gic to carry out the request belongs in {{res_stasis.so}}, or in the underl=
ying 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 t=
he different interfaces actually act consistently.

h1. Test Plan

Each controller in the RESTful API should have at least one integration tes=
t validating that function. Many will have multiple tests to validate failu=
re conditions (originate failed, etc.).

|| Test || Level || Description ||
| stasis_obj_to_json | Unit | Tests Stasis object to JSON codec |
| stasis_obj_to_xml | Unit | Tests Stasis object to XML codec |

h1. Project Planning

h2. JIRA Issues

{jiraissues:url=3Dhttps://issues.asterisk.org/jira/sr/jira.issueviews:searc=
hrequest-xml/11923/SearchRequest-11923.xml?tempMax=3D1000|anonymous=3Dtrue}

h2. Contributors

|| Name || E-mail Address ||
| [~dlee] | dlee at digium.com |

h1. Reference Information

* Stable identifier for channels:
** [~dlee:Stable Identifiers for Asterisk]
** [http://lists.digium.com/pipermail/asterisk-dev/2009-May/038430.html]
** [http://lists.digium.com/pipermail/asterisk-dev/2010-June/044754.html]
** [https://reviewboard.asterisk.org/r/760/]
* Stasis API:
** [http://lists.digium.com/pipermail/asterisk-dev/2012-November/057814.htm=
l]
*** Thread continues here: [http://lists.digium.com/pipermail/asterisk-dev/=
2012-December/057853.html]
** [http://lists.digium.com/pipermail/asterisk-dev/2012-December/057893.htm=
l]

h1. Footnotes

* {anchor:bad-name} While it may stand for &quot;Some Thought Actually Spen=
t In Specification&quot;, suggestions for a better name are welcome.

{numberedheadings}</pre> </td>
                                                            </tr>
                                                        </tbody>
                                                    </table>
                                                </div>
                                            </div>
                                        </div>
                                        <table id=3D"email-actions" class=
=3D"email-metadata" cellspacing=3D"0" cellpadding=3D"0" border=3D"0" width=
=3D"100%" style=3D"border-top: 1px solid #bbb; color: #505050; margin: 8px =
0 0 0; padding: 0; color: #505050">
                                            <tbody>
                                                <tr>
                                                    <td class=3D"left" vali=
gn=3D"top" style=3D"font-size: 13px; padding-top: 8px; max-width: 45%; text=
-align: left"> <span class=3D"email-list-item"><a href=3D"https://wiki.aste=
risk.org/wiki/display/AST/Asterisk+12+API+Improvements" style=3D"color: #32=
6ca6; text-decoration: none">View Online</a> </span> <span class=3D"email-l=
ist-divider" style=3D"color: #505050; padding: 0 0.350em">&middot;</span> <=
span class=3D"email-list-item"><a href=3D"https://wiki.asterisk.org/wiki/pl=
ugins/likes/like.action?contentId=3D21464586" style=3D"color: #326ca6; text=
-decoration: none">Like</a> </span> <span class=3D"email-list-divider" styl=
e=3D"color: #505050; padding: 0 0.350em">&middot;</span> <span class=3D"ema=
il-list-item"><a href=3D"https://wiki.asterisk.org/wiki/pages/diffpagesbyve=
rsion.action?pageId=3D21464586&amp;revisedVersion=3D19&amp;originalVersion=
=3D18" style=3D"color: #326ca6; text-decoration: none">View Changes</a> </s=
pan> <span class=3D"email-list-divider" style=3D"color: #505050; padding: 0=
 0.350em">&middot;</span> <span class=3D"email-list-item"><a href=3D"https:=
//wiki.asterisk.org/wiki/display/AST/Asterisk+12+API+Improvements?showComme=
nts=3Dtrue&amp;showCommentArea=3Dtrue#addcomment" style=3D"color: #326ca6; =
text-decoration: none">Add Comment</a> </span> </td>
                                                    <td class=3D"right" wid=
th=3D"50%" valign=3D"top" style=3D"font-size: 13px; padding-top: 8px; text-=
align: right"> <span class=3D"email-list-item"><a href=3D"https://wiki.aste=
risk.org/wiki/users/removespacenotification.action?spaceKey=3DAST" style=3D=
"color: #326ca6; text-decoration: none">Stop watching space</a> </span> <sp=
an class=3D"email-list-divider" style=3D"color: #505050; padding: 0 0.350em=
">&middot;</span> <span class=3D"email-list-item"><a href=3D"https://wiki.a=
sterisk.org/wiki/users/editmyemailsettings.action" style=3D"color: #326ca6;=
 text-decoration: none">Manage Notifications</a> </span> </td>
                                                </tr>
                                            </tbody>
                                        </table> </td>
                                </tr>
                            </tbody>
                        </table> </td>
                </tr>
                <tr>
                    <td id=3D"email-footer" align=3D"center" style=3D"font-=
size: 13px; padding: 0 16px 32px 16px; margin: 0"> <small style=3D"font-siz=
e: 11px"> This message was sent by <a class=3D"email-footer-link" style=3D"=
color:#505050;font-size:11px;text-decoration:none;; color: #326ca6; text-de=
coration: none; color: #505050; font-size: 11px" href=3D"http://www.atlassi=
an.com/software/confluence">Atlassian Confluence</a> 5.0.3, <a class=3D"ema=
il-footer-link" style=3D"color:#505050;font-size:11px;text-decoration:none;=
; color: #326ca6; text-decoration: none; color: #505050; font-size: 11px" h=
ref=3D"http://www.atlassian.com/software/confluence/overview/team-collabora=
tion-software?utm_source=3Demail-footer">Team Collaboration Software</a> </=
small> </td>
                </tr>
            </tbody>
        </table>
    </body>
</html>
------=_Part_809_1585296633.1372799700004
Content-Type: image/jpeg; name=avatar_16181e6326f183784f186951c83d98b8
Content-Transfer-Encoding: base64
Content-ID: <avatar_16181e6326f183784f186951c83d98b8>
Content-Disposition: attachment; 
	filename=avatar_16181e6326f183784f186951c83d98b8

/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcU
FhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgo
KCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAAwADADASIA
AhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQA
AAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3
ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWm
p6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEA
AwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSEx
BhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElK
U1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3
uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwDpYPEk
mieFb29wJfspzbl4zy/A5xx3FfPt9eXE88s0zs8rsWdieSTX1F8W7eG+8CatFbzYi8hbiAKAM7Dy
uB16ivmLTrObUNPkulXcFyNoHPWvBy2KjFy63Nowb0KMF07sN2QAc8V2GhaO2oRlypxjORVlfCzr
pqSm2Zt+0/L7/wCRXpWgaH/ZlmsZGWIwfavYhWb0KeH6s880MTaXqAkt3ZZYyQDnr7H6171e31pd
aHFcyyJtdcjzgMIwAIHHbP8ASvFPEqSWOvNGijZNyv1r0WPS7/TNOk0uUxz/AG0ecCIi2xQOcnsf
pmvMzWPOovqZRjyvQ8z0zx/rlzCUmvxKkZLn7QgJRTwTk/XpUOi6dc6O80MDk/OdjFeoPIzXDpdT
xTeVcW0oD5RmTPz49j7ivS/COpR6i8AkGGEYDA+o/wDrYrWlBQbOuMdbG5oN9qTBIbwqZHQsoCgF
SOxqOCDVJ75JTeOykHcrEgA9gAO1W5ZI4dbt3ydiqQ20ZrctLhGXcUKqT8u7Ga6ItL3kauN/dZUv
dLjuXsprhcywnJIOD+delWwW4s7RpJmMkagkg9TjkV5X4m11tKaOS3iEjuCADk4x9KteCPGmhyv5
OoS39m7fxM6yRj8cZFOryykuY4qkJSjaB11z8PvDczyldOjieQ4zCxUDHQj0NZHiD4c29hHJqumX
kzPFHvkilYEMAOSDjg4H6V6Brt5YaMha8clnGVjUAsfwry/xl4h1S9VhZsYbUqVZBySD3NY08PUl
71tDWVeCaimcwu5bsvEzGI9sA1t20S+WJJfMOORvPT8KxI4ZIJVkgYBWGcHkVr20cjMrXE3mDsAM
CtodjSUtC9dfD5fF9pHfLdywTRExhduVxjI6cg1c0j4SanaDc95YzyLGPLZ1LKT6EEencGtbwvf3
Fl5skDkRsANp5BOeuK7Gx8TQs6x3cZjKj7ydPritpYGpJc61Rw/XYxlyH//Z
------=_Part_809_1585296633.1372799700004
Content-Type: image/png; name=page-icon
Content-Transfer-Encoding: base64
Content-ID: <page-icon>
Content-Disposition: attachment; filename=page-icon

iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAAPFBMVEX///+1tbWwsLCtra3////5
+fmLi4vZ2dnT09P8/PzPz8+rq6uhoaHR0dFycnJwcHB6enp4eHiDg4OAgIBog/vRAAAADnRSTlMA
IiJV3e7u7u7u7u7u7rDOyYEAAABUSURBVHhepcpLDoAwCABRqkBbP9Dq/e9qLYS1ibN8GQBYWFVG
fQWLWyFEJG0uknGmuz+CDnjYEzDqDpF8BrV+HBRHNThjyBP42qpBufmFxOIpJ3gAPTUGaYiilrsA
AAAASUVORK5CYII=
------=_Part_809_1585296633.1372799700004--



More information about the asterisk-wiki-changes mailing list