Use Cases

Mailboxes/MWI

1. App can create a custom mailbox
   1. Are mailboxes given names, or do they have unique id's?
      Mailboxes have unique IDs that are - essentially - their names. The naming scheme is [email protected], where context is just another identifier that provides a way to group mailboxes together. From the perspective of a SIP phone or something else that subscribes to mailbox state, it subscribes to this identifier.
   2. Does a mailbox's existence persist across restarts? What about it's state?
      No. A restart blows it out of Stasis cache. The VoiceMail provider API (provided in app.h) allows consumers of mailbox state to query a voicemail provider for the current state when that state is not in the cache. From the perspective of a phone, the MWI should not change if Asterisk is restarted. Thus, ARI will also have to be a voicemail provider. In practice, however, the only time when this occurs is on initial system start up - and so long as you receive a notification that someone wants the current state of the mailbox and you send it to them, this should work just fine.
2. App can associate custom mailbox with a blinky light on a device
   1. Does this happen via the app, or via configuration?
      This is done by the phones, not the app. The app can't associate a mailbox with a device. The app can only provide state for the mailbox that a device wants. 
3. App can publish a new state for a mailbox
   1. Are there any common attributes for mailbox state (unplayed message count, last message timestamp, etc.)
      It's all device specific. In practice, it is a new message count/old message count. Theoretically, however, you could want the state of any portion of someone' s mailbox, i.e., any folder message count. You could also want to differentiate between message priorities (normal, urgent, priority, etc.)

Presence

1. App can publish new presence state
   1. Are there any common attributes for presence state (state, last change timestamp, etc.)
      Presence State is only the state. State values, however, can be arbitrary.

Device State

1. App can create a custom device state
   1. This can be used as an extension state in the dialplan
      Correct, if someone put it in as an extension state. In fact, at some level, it has to be in the dialplan: if there isn't a hint for it in the dialplan, no one (device wise) can subscribe to it. That does make ARI have to have a level of dialplan integration that is unfortunate.
2. App can publish new device state
   1. Are there any common attributes for device state (state, last change timestamp, etc.)
      It's ultimately device specific. When a device subscribes for the state of something, it states how it wants to receive the events. The tricky part becomes when what it subscribes for is ultimately a very device specific concept (such as the SNOM DIALOG_INFO_XML stuff.) The fact that these things exist - and someone may want to be able to create event bodies for them through ARI - is part of what leads to having a very generic event publish API.

Proposal one: Generic topics

API

GET /topics List[Topic] - list all topics, with optional filter for type

GET /topics/{topicId} Topic - get information about a specific topic

DELETE /topics/{topidId} - 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/{topicId}/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.

/applications/{applicationName}/subscription will be updated to allow for an ARI client to subscribe to any topic in Asterisk.

Data model

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

Proposal two: First class resources

API

/mailboxes/...

/devicestates/...

/presencestates/...

Data Model

Mailbox

• id: string
• custom: object - custom mailbox state

DeviceState

• id: string
• custom: object - custom device state

PresenceState

• id: string
• custom: object - custom presence state

Events

Mailbox{Created,Changed,Destroyed}

• mailbox: Mailbox

DeviceState{Created,Changed,Destroyed}

• device_state: DeviceState

PresenceState{Created,Changed,Destroyed}

• presence_state: PresenceState

I don't have any comments or problems with this approach. Since the actual 'state' is custom and is not provided by the API, it is proving my point that these concepts all end up being fundamentally identical in terms of their attributes, events, and general usage. I think the operations upon them will end up being very similar as well.