[asterisk-app-dev] Blinky Lights Proposal

Tue Nov 5 12:26:48 CST 2013

On Tue, Nov 5, 2013 at 11:07 AM, David M. Lee <dlee at digium.com> wrote:

>
> On Oct 31, 2013, at 7:58 PM, Matthew Jordan <mjordan at digium.com> wrote:
>
>
>
<snip>

> >
> > 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.
>
> If the implementation is really different, then I question whether the
> API's really ought to be similar. Having a consistent API is excellent, but
> using the same API for different but similar things can become problematic
> where they become dissimilar.
>

Well, internal implementation details shouldn't impact API decisions. In
Asterisk, MWI, device state, and presence state all grew in different ways
at different times - so the fact that they are dissimilar in how they were
implemented can be chalked up to "organic growth" if nothing else.

>From an API perspective, when you consider that all three things follow a
publish/subscribe model; that all three have interoperability concerns with
how physical devices will want to receive information; and that in all
three Asterisk is both a producer and consumer of state (although more
commonly a producer of said state), then in any API you create for each,
there are bound to be a lot of similarities  I approached it from that
perspective, although I agree it ends up losing some details as a result.

>
> > The following is a proposal on how I think this might work:
> >
> > 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.)
> >
> > Objects:
> >
> > Topic:
> >     type: string - Valid types initially would be 'mailbox', 'device',
> 'presence'
> >     uri: string - The URI subscribers use to subscribe to the topic
> >     subscribers: List[Subscriber] - A list of active subscriptions
> >     id: string - A unique ID for the topic
> >
> > Subscriber
> >     id: string - A unique ID for the subscriber
> >     topic_id: string - The topic ID this subscription refers to
> >     endpoint: Endpoint - If available, the endpoint that subscribed to
> this Topic
> >
> > TopicSubscriptionCreated : Event - Event raised when a new subscription
> is created for a topic
> >     subscriber : Subscriber
> >     topic: Topic
> >
> > TopicSubscriptionDestroyed : Event - Event raised when a subscription is
> destroyed for a topic
> >     subscriber : Subscriber
> >     topic : Topic
> >
> > TopicEvent : Event - Event raised in relation to a topic
> >     topic : Topic
> >     body : JSON
> >
> > TopicCreated : Event - Event raised when a new topic is created
> >     topic : Topic
> >
> > TopicDestroyed : Event - Event raised when a topic is destroyed
> >     topic : Topic
>
> From ARI’s perspective, what are the use cases for needing the
> Created/Destroyed events for topics and subscriptions?
>

Currently, when a phone subscribes for MWI or extension state, Asterisk
will typically immediately publish the known state of the mailbox/extension
state to the phone.

In this case, that information is coming from an external source. As such,
Asterisk may not have that information, as the Stasis cache will not be
populated with that information on startup. That information has to come
from the external source, i.e, the ARI application. Notifying the ARI
application that a subscription has occurred lets the application choose
whether or not it wants to inform the new subscriber of the current state.

>
> You’re exposing a Subscriber object here, but there’s no associated
> resource for managing the subscriber. What’s that used for?
>

Information only. You would want to potentially know something about who
subscribed to what if you have different phone models at play, e.g., I know
that Mark's SIP phone is a SNOM and John's SIP phone is a Cisco, and they
don't both want the same device state package. We could conceivably allow
the ARI application to destroy subscriptions, but if it's a phone (or
something other piece of equipment), they might just re-subscribe anyways.
It felt appropriate to have something represent the subscription in the
event.

>
> > Operations:
> >
> > GET /topics List[Topic] - list all topics, with optional filter for type
> > GET /topic Topic - get information about a specific topic
> > DELETE /topic - destroy a topic. This should implicitly unsubscribe all
> subscribers.
> > POST /topics Topic - create a new topic. When you create a topic, you
> are implicitly subscribed to that topic.
> >     type: The type of topic to create. Valid types initially would be
> 'mailbox', 'device', 'presence'
> >     uri: The URI subscribers will use to subscribe to the topic
> > 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.
>
> Aside from merging together several potentially separate concerns, there’s
> a lot of unREST in this proposal :-P
>

Obviously the generic event packages is not very REST-ful. I think any
proposal is going to have to find a way to send device specific event
packages to specific phone models - which means you're going to be leaving
the glory of REST behind at some point.

>
> > /applications/{applicationName}/subscription will be updated to allow
> for an ARI client to subscribe to any topic in Asterisk.
> >
> > 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.
> >
> > 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.
> >
> > Thoughts? Comments?
>
> By weaving these three concepts together, I worry that in an attempt to
> make the interface ‘easy’, we end up making it complicated. Presence,
> device state and mwi become hidden in the types of topics you create.
> Creating individual resources for these topics seems like a simpler, and
> more clear, approach.
>

I can't argue that individual resources is easier to approach. However, I
think there's a lot of overlap between some of the fundamentals with all
three of these resources that is going to make them generally identical.

>
> I at least like to see what individual /mailboxes, /devicestates, and
> /presencestates resource would like like before we attempt to combine them
> at the API level. If we find that these are three different names for
> identical API’s, then maybe merging them is a good idea. But my gut tells
> me that we’ll find subtle differences between them.
>
> I’m not familiar enough with the use cases to put together an API
> counterproposal.
>
> This seems like a big/important enough topic to get its own wiki page. So
> I started one: https://wiki.asterisk.org/wiki/x/YQ2UAQ
>
>
I'll comment more there!

-- 
Matthew Jordan
Digium, Inc. | Engineering Manager
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at: http://digium.com & http://asterisk.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-app-dev/attachments/20131105/19ae336f/attachment.html>