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>
