[asterisk-app-dev] MWI/Mailboxes ARI specifications

[Daniel Jenkins]

Hi,

I've added comments below, please forgive me if I've missed something in
previous discussions about the ARI, not had a chance to keep up with it all
for a little while

On Wed, Dec 18, 2013 at 10:25 PM, Jonathan Rose <jrose at digium.com> wrote:

> ARI Mailboxes resource
>
> I'm currently starting on some basic implementation of the mailboxes
> resource described at
> https://wiki.asterisk.org/wiki/display/AST/Blinky+Lights+API
>
> Data Model:
>
> name: string        name of the mailbox
> new_messages: int   count of messages that have not been marked as old
> old_messages: int   count of messages that have been marked as old
>
> As such, I'm currently writing stub functions for the following commands
>
> Method   URL                        Return type
> GET      /mailboxes                 list(mailbox)
> POST     /mailboxes                 mailbox
> GET      /mailboxes/{mailboxName}   void
> PUT      /mailboxes/{mailboxName}   void
> DELETE   /mailboxes/{mailboxName}   void
>
> GET /mailboxes
> List all mailboxes in Asterisk
>

Is this purely returning a list of mailbox ids/names or mailbox objects
with a subset of data in compared to  /mailboxes/{mailboxName}?  I can see
why I'd want to list all mailboxes and how many messages are in each one.

>
> POST /mailboxes
> Create an empty mailbox
> query parameters:
>   mailboxName - name for the mailbox
>

Would this not possibly return an error if the name already existed? Is the
name mandatory or optional? If optional, would it just create a randomly
named mailbox? I don't see why you'd want to do this but...


> GET /mailboxes/{mailboxName}
> Get the current state of a mailbox
> path parameters:
>   mailboxName - name of the mailbox
> error responses:
>   404 - Mailbox not found
>

What kind of response would a mailbox look like? An Object with what
parameters in?


>
>

> PUT /mailboxes/{mailboxName}
> Change the state of a mailbox
> path parameters:
>   mailboxName - name of the mailbox to be modified
> query parameters:
>   new_messages - count of new messages in the mailbox
>   old_messages - count of old messages in the mailbox
> error responses:
>   404 - Mailbox not found
>   409 - Mailbox not in a stasis application
>

Something about this seems wrong to me but I can't put my finger on it, a
mailbox only has messages and so messages shouldn't need to be in the name
of params as it's self documenting as such. I can't access the wiki to get
access to other route's documentation right now so I'm not sure if this is
in keeping with the rest of the ARI or not.

Are both of these parameters required? If there are X number of messages in
the mailbox and only 2 are new then old messages is X-2; or am I missing
something? If they are both required then will there be validation to say
that old + new must equal the total number of messages in the mailbox?


>
> DELETE /mailboxes/{mailboxName}
> Delete an existing mailbox
> path parameters:
>   mailboxName -name of the mailbox to be deleted
> error responses:
>   404 - Mailbox not found
>   409 - Mailbox not in a stasis application
>

Are there any other reasons why a mailbox couldn't be deleted? What if it
was being written to at that moment?


> Events:
> MailboxStateChanged
>   The contents of a mailbox have changed
>   mailbox - name of the mailbox that was changed
>

Would it only give you the fact it changed? Or would it detail the change
itself?


>
> MailboxUpdateRequested
>   When Asterisk starts, it has no mailbox state from the external
>     application. This event requests that the external voicemail
>     application put the current mailbox state back into Asterisk.
>   mailbox - name of the mailbox Asterisk
>
> I'm still a little hazy on some details, such as whether or not
> mailbox data will be persisted. There was something of a debate
> over the topic that I couldn't quite tell whether it reached a
> concensus and the wiki proposal contained conflicting information.
> I'm unsure how that will affect the ARI work.
>
> If anyone has any input into this, I'd appreciate hearing it before
> getting too deep into the coding of it.
>
> Also, it's worth noting that the Mailboxes resource will not be
> released with Asterisk 12.0, and will likely be a new feature
> slightly down the road (targeting 12.1).
>
> If all of this seems appropriate, I'll go ahead and start trimming
> the more generic topics proposal and getting the details fleshed
> out on the wiki page.
>

Great to see more stuff being added to the ARI :)


> --
> Jonathan R. Rose
> Digium, Inc. | Software Engineer
> 445 Jan Davis Drive NW - Huntsville, AL 35806 - US
> direct +1 256 428 6139
>
> Check us out at: http://digium.com & http://asterisk.org
>
>
> _______________________________________________
> asterisk-app-dev mailing list
> asterisk-app-dev at lists.digium.com
> http://lists.digium.com/cgi-bin/mailman/listinfo/asterisk-app-dev
>
>
Dan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-app-dev/attachments/20131219/a308dc24/attachment-0001.html>