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

[Paul Belanger]

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.

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