<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:Wingdings;
panose-1:5 0 0 0 0 0 0 0 0 0;}
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0cm;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman","serif";}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
span.EmailStyle17
{mso-style-type:personal-reply;
font-family:"Calibri","sans-serif";
color:#1F497D;}
.MsoChpDefault
{mso-style-type:export-only;
font-family:"Calibri","sans-serif";
mso-fareast-language:EN-US;}
@page WordSection1
{size:612.0pt 792.0pt;
margin:72.0pt 72.0pt 72.0pt 72.0pt;}
div.WordSection1
{page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
</head>
<body lang="EN-GB" link="blue" vlink="purple">
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US">Hi Matt,<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US">Good idea, it’s something that was always a bug-bear of mine in AGI.
<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US">One question, what are your ideas for the filtering (you mention by type) but it seems to be this could still be a very large list
of returned objects. Just a thought that’s all.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US">Vote +1
</span><span style="font-size:11.0pt;font-family:Wingdings;color:#1F497D;mso-fareast-language:EN-US">J</span><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US"><o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D;mso-fareast-language:EN-US"><o:p> </o:p></span></p>
<p class="MsoNormal"><b><span lang="EN-US" style="font-size:11.0pt;font-family:"Calibri","sans-serif"">From:</span></b><span lang="EN-US" style="font-size:11.0pt;font-family:"Calibri","sans-serif""> asterisk-app-dev-bounces@lists.digium.com [mailto:asterisk-app-dev-bounces@lists.digium.com]
<b>On Behalf Of </b>Matthew Jordan<br>
<b>Sent:</b> 01 November 2013 00:59<br>
<b>To:</b> Asterisk Application Development discussion<br>
<b>Subject:</b> [asterisk-app-dev] Blinky Lights Proposal<o:p></o:p></span></p>
<p class="MsoNormal"><o:p> </o:p></p>
<div>
<p class="MsoNormal">Hey everyone -<o:p></o:p></p>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">At AstriDevCon, we mentioned that two features ARI would need were the ability to raise MWI and the ability to publish state (device state, but theoretically, any event package for some subscribable resource). Initially, we discussed needing
two resources in ARI - one that represents the state of mailboxes, and one that represents the state of a "device".<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">The more we've thought about it, the more it feels like - from ARI's perspective - these are the same concepts. From the perspective of an ARI client, you want the ability to define a resource that someone can subscribe to. You want to
be notified when something subscribes to it; when they unsubscribe to it; and when a resource's state changes. In turn, you want to publish state about that resource to the subscribers. The fact that the resource is a mailbox, or a device, or who knows what
else - is immaterial. The application itself should determine this.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">(Plus, we forgot that in addition to device state and MWI, there's also presence state in Asterisk. So we were already up to 3 things anyway)<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">We need a more generic concept - a 'blinky light' resource, if you will.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">The trick, unfortunately, is that in the guts of Asterisk, these are not the same concepts. MWI and device state (or presence state, for that matter) are all handled very differently. As much as it'd be fun to say "let's unify all the implementations!"
- that's unrealistic and potentially harmful. So whatever we choose, there has to be a way to map the generic concept back to the actual implementation inside Asterisk.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">The following is a proposal on how I think this might work:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Add a new resource to ARI to represent a generic resource that can be subscribed to/published about, 'topics'. A topic is something that something can subscribe to, that has state, and that the ARI client can publish state about. (Note
that I chose the name 'topic' as it's what the XMPP folks used for their publish/subscribe XEP (XEP-0060), and 'resource' isn't a good name as it's a generic term in REST. Hopefully it doesn't get too confusing with Stasis message bus topics.)<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Objects:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Topic:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> type: string - Valid types initially would be 'mailbox', 'device', 'presence'<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> uri: string - The URI subscribers use to subscribe to the topic<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> subscribers: List[Subscriber] - A list of active subscriptions<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> id: string - A unique ID for the topic<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Subscriber<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> id: string - A unique ID for the subscriber<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> topic_id: string - The topic ID this subscription refers to<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> endpoint: Endpoint - If available, the endpoint that subscribed to this Topic<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">TopicSubscriptionCreated : Event - Event raised when a new subscription is created for a topic<o:p></o:p></p>
</div>
<div>
<div>
<p class="MsoNormal"> subscriber : Subscriber<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> topic: Topic<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">TopicSubscriptionDestroyed : Event - Event raised when a subscription is destroyed for a topic<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> subscriber : Subscriber<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> topic : Topic<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">TopicEvent : Event - Event raised in relation to a topic<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> topic : Topic<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> body : JSON<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">TopicCreated : Event - Event raised when a new topic is created<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> topic : Topic<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">TopicDestroyed : Event - Event raised when a topic is destroyed<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> topic : Topic<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
</div>
<div>
<p class="MsoNormal">Operations:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">GET /topics List[Topic] - list all topics, with optional filter for type<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">GET /topic Topic - get information about a specific topic<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">DELETE /topic - destroy a topic. This should implicitly unsubscribe all subscribers.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">POST /topics Topic - create a new topic. When you create a topic, you are implicitly subscribed to that topic.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> type: The type of topic to create. Valid types initially would be 'mailbox', 'device', 'presence'<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> uri: The URI subscribers will use to subscribe to the topic<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">POST /topics/publish - publish an event to a topic. Events are passed as JSON, and are opaque from the perspective of ARI. It would be up to the specific topic types to understand the event packages.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">/applications/{applicationName}/subscription will be updated to allow for an ARI client to subscribe to any topic in Asterisk.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Note that a topic doesn't have to be something created by ARI - Asterisk will create a *lot* of topics by itself. There would be a topic for all mailboxes created by voicemail providers; a topic for all producers of extension state (at
a minimum; devices as well); a topic for all producers of presence state. Much like the Endpoints resource, the Topics resource lets an ARI client subscribe to other things in the system other than what is directly in their application, so that the client
can choose to have knowledge of the whole system, even if it only affects a part.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">This is quite a big project, but a very necessary one. There's only one thing that has to be fixed in ARI before we can do this - namely the ability to POST JSON (thanks Paul!) But other than that, I don't think there are any technical
barriers to this approach.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Thoughts? Comments?<o:p></o:p></p>
</div>
<div>
<div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<p class="MsoNormal">-- <o:p></o:p></p>
<div>
<div>
<p class="MsoNormal">Matthew Jordan<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">Digium, Inc. | Engineering Manager<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">445 Jan Davis Drive NW - Huntsville, AL 35806 - USA<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">Check us out at: <a href="http://digium.com" target="_blank">
http://digium.com</a> & <a href="http://asterisk.org" target="_blank">http://asterisk.org</a><o:p></o:p></p>
</div>
</div>
</div>
</div>
</div>
</div>
</body>
</html>