[asterisk-app-dev] Changing POST /bridges/{bridgeId}/addChannel

[Paul Belanger]

On Wed, Oct 16, 2013 at 2:20 PM, Paul Belanger
<paul.belanger at polybeacon.com> wrote:
> On Wed, Oct 16, 2013 at 1:56 PM, David M. Lee <dlee at digium.com> wrote:
>>
>> On Oct 15, 2013, at 6:30 PM, Daniel Jenkins <dan.jenkins88 at gmail.com> wrote:
>>
>> I know Mr Lee said that he didn't go full on HATEAOS style, but your verbs
>> are meant to be your GET, POST, PUT and DELETE methods and so the fact
>> you're doing a post means create and the fact you're doing PUT means you're
>> adding...
>>
>> Is this a rabbit hole we want to go down? I just don't like routes that
>> contain verbs, it feels messy to me.
>>
>>
>> I agree that it's messy, but I decided to make some compromises for the sake
>> of readability and usability. We avoid verbs when we can, but there are
>> cases where it's just not practical.
>>
>> Here was the process I went through designing the /bridges API.
>>
>> Channels can exist without bridges, so it's better if there are no bridge
>> related operations on the channel. That avoids a cyclic dependency between
>> bridges and channels.
>>
> I guess it is 50 / 50, both appear to be valid ways of looking at it.
> Personally I just think
>
> POST /channels/{channelId}/bridge
> DELETE /channels/{channelId}/bridge
>
> is good for a single operation and:
>
> POST /bridges/{bridgeId}/channels
> DELETE /bridges/{bridgeId}/channels
>
> would be for bulk.
>
>> Here was my first thought:
>>
>> POST /bridges/{bridgeId}/channels/{channelId} - add a channel to a bridge
>> DELETE /bridges/{bridgeId}/channels/{channelId} - remove a channel from a
>> bridge
>>
>> That's okay, but you've lost the ability for bulk operations. So now you'll
>> want to post to the /channels resource itself. Without putting verbs in the
>> route, you're left with this:
>>
>> PUT /bridges/{bridgeId}/channels ["channelId", …] - update the channel list
>>
>> (Look, Dan. I used a PUT :-D)
>>
> So that was my though process as well, but I think we need to focus on
> single operations to start, then deal with bulk.  Going the other way
> seems to be more work.
>
>> Okay, now we can update the list of channels that are in the bridge. But
>> this has its own problems. What if other channels are being added to the
>> bridge concurrently? Now you have the danger of write conflicts causing
>> changes to be lost.
>>
>> That's a problem that could be solved, by adding a version number to the
>> resource and doing optimistic locking, but now the application developer has
>> to deal with 409 Conflict failures when the channel list is updated
>> concurrently.
>>
>> I always came around to having /addChannels and /removeChannels routes just
>> to make the API usable. Since we had to have them anyways, I didn't see the
>> point of having the 'clean' version, too.
>>
> So, I actually tried this last night, using multiple channels but here
> is the issue that I ran into with bulk.  I have a list of channels,
> some that we in stasis and some not, addChannels failed.  However, I
> was surprised to see that no actually channels made it into the
> bridge, instead I got back a generic message about channels does not
> exist.  Of course, this now opens up the issue of how to tracking
> which channel was the issue and generate error messages / return
> codes.  Now we are starting to move into more complex sceneries which
> is all good, but now more and more logic has to be created to handle
> it.
>
> So, going back to the point of single vs bulk, I think we should focus
> on the single operation, have said library or application you are
> working with take the hit and generate the additional request and once
> we see how people are using the ARI, then work to optimize performance
> issues but adding specific bulk functions.
>
> Because honestly, if we are saying the work lot need for additional
> HTTP requests are going to hinder asterisk, then I think we have a
> bigger issue at play.  Then to me, we move http out side of asterisk
> and write directly to the messagebus and have asterisk deal with it
> then.
>
So I started thinking more about this from a library how are we
planning on indicating back the the client which channel failed on a
bulk operation.  The issue that I have, is even if we return a list
while the error message, now we have to add a parser to parse the
string and extract the values.  Ideally we'd return json format, but
I've never seen that for an error.  Now, we're building upon return
message strings to extract data.

With single operations, I the client knows exactly which channel fails.

-- 
Paul Belanger | PolyBeacon, Inc.
Jabber: paul.belanger at polybeacon.com | IRC: pabelanger (Freenode)
Github: https://github.com/pabelanger | Twitter: https://twitter.com/pabelanger