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

[David M. Lee]

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.

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)

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.

-- 
David M. Lee
Digium, Inc. | Software Developer
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at:  www.digium.com  & www.asterisk.org

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-app-dev/attachments/20131016/737c0af0/attachment.html>