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. In addition to generating a ton of boilerplate code for implementin=
g the API, it also generates [the documentation mentioned above|AST:Asteris=
k 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> 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 "Some Thought Actually Spen=
t In Specification", 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">·</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">·</span> <span class=3D"ema=
il-list-item"><a href=3D"https://wiki.asterisk.org/wiki/pages/diffpagesbyve=
rsion.action?pageId=3D21464586&revisedVersion=3D21&originalVersion=
=3D20" 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">·</span> <span class=3D"email-list-item"><a href=3D"https:=
//wiki.asterisk.org/wiki/display/AST/Asterisk+12+API+Improvements?showComme=
nts=3Dtrue&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=
">·</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.1.5, <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_802_1890232722.1376949840049
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_802_1890232722.1376949840049
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_802_1890232722.1376949840049--
More information about the asterisk-wiki-changes
mailing list