[asterisk-app-dev] MWI/Mailboxes ARI specifications
Jonathan Rose
jrose at digium.com
Thu Dec 19 12:25:26 CST 2013
On Thu, Dec 19, 2013 at 11:29 AM, Daniel Jenkins <dan.jenkins88 at gmail.com>wrote:
> 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.
>
Well, it will be returning the list of mailbox objects, and since a mailbox
object contains the state of the mailbox, the count of old and new messages
should be contained within that. Functionally, it will be like with the
existing deviceState objects. You can get them individually with
mailboxes/{mailboxName} if you know the name of the mailbox... if you get
them with GET /mailboxes instead of /mailboxes/mailboxName, you'll get the
full list instead... which will output them in the usual descriptive
format... which I'm guessing would looks something like:
[ { "name": "alice",
"new_messages": 5,
"old_messages": 3 },
{
"name": "bob",
"new_messages": 4,
"old_messages": 0
} ]
>
>> 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...
>
Absolutely it could return an error. Conflicts with existing named
mailboxes are a possible reason. Also internal problems such as memory
allocation failures. But since I wrote this, I've noticed that deviceStates
currently handles this in a slightly different way. Instead of having an
explicit POST function, the PUT doubles as the method for creating objects
if a PUT is used with a name that doesn't exist, so this function is
probably not actually going to exist in the final implementation. That
also means that name conflicts wouldn't be an issue for creation since
it'll just edit the mailbox it's pointed at. On the other hand, pointing
to a mailbox that is owned by something other than Stasis will result in a
failure as well since Stasis applications shouldn't be allowed to
manipulate non Stasis mailboxes. I'm currently following the same model as
deviceStates, so name will be mandatory for the PUT function unless someone
feels strongly that we should be able to assign a name if none is given.
>
>> 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?
>
As above, it would be a JSON blob which was described by the object model
that I put near the beginning of the email. More specifically, it would
look like this:
{
"name": "bob",
"new_messages": 4,
"old_messages": 0
}
>
>
>>
>>
>
>> 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?
>
Ok, so again, basing this off of the DeviceState model that already exists,
PUT will be able to both create and modify mailboxes. The name of the
mailbox here is a path parameter, so listing it in the parameters is just
for the sake of documenting that particular value. It's not a separate
variable that needs to be specified by the message or anything. I'm unsure
if the message count variables should be required. After all, if the
mailbox already exists and you only specify one, we could simply assume
that the other value should stay the same. Likewise, if the mailbox is
being created, unspecified values could simply be assumed as 0. I don't
believe there will necessarily be any relationship between new and old
messages and the mailbox object doesn't track a total, it simply tracks old
and new separately and those can be taken and added together to deduce the
total.
>
>
>>
>> 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?
>
I imagine if it was being written to at the time of the DELETE request, the
response would simply be delayed until the mailbox could successfully be
acquired and deleted. Presently, these are the only documented error
responses for the DELETE method on Device States as well, so I don't
anticipate any additional possibilities currently.
>
>
>> 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?
>
Presumably based on that documentation the change would not be detailed
beyond the simple fact that the specific mailbox changed and at that point
it would be up to the consumer to retrieve the mailbox and examine the new
values and determine what to do with them.
--
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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-app-dev/attachments/20131219/26aabe40/attachment.html>
More information about the asterisk-app-dev
mailing list