[asterisk-dev] ARI feedback

[Billy Chia]

+1 on most of Paul's comments, however, I'd be against versioning in the
URI. Although this is a popular and well understood mechanism for REST API
versioning, it seems like it would cause problems in a
communications-centric (Asterisk) environment. For example, consider the
following scenario:

I have an endpoint for Bob and we use URI versioning

GET /v1/endpoints/sip/bob

then I update some of my Asterisk servers to v2

GET /v2/endpoints/sip/bob

I have two different URIs but they refer to the same resource. In a large
distributed environment this could be very difficult to handle client-side.
The client has to intelligently request different resources (which is
really the same resource) depending on the server version. Also, if some of
the clients have the URI cached it's now broken with the server-side
upgrade.

It seems that using content-type for versioning would be a cleaner
solution.

I'm parroting / paraphrasing Peter Williams
http://barelyenough.org/blog/2008/05/versioning-rest-web-services/

Note that Github used URI versioning in v1 and v2 of its API, but updated
to content-type in v3:

http://developer.github.com/v3/media/

I suspect other popular APIs will follow suit.

*Billy Chia*
Digium, Inc. | Product Marketing Manager
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
direct: +1 256-428-6099
*Check us out at*: www.digium.com & www.asterisk.org


On Sat, Oct 12, 2013 at 5:13 PM, Paul Belanger <paul.belanger at polybeacon.com
> wrote:

> Back from Astricon and already hacking our queue app to hook into ARI,
> however I'm curious about how we are going to handle feedback of the
> ARI APIs? How locked down are we on things?
>
> For example, it would be nice when we pass back a UUID (eg: bridging)
> that we named it uuid, not id.  I know it is trivial, but seems to
> help me remember the format better.
>
> Another example, again in bridging is on POST /bridges it expect a
> parameter as 'type' however the API returns 'bridge_type', again, it
> would be nice to have them both the same.  And since 'type' is usually
> a reserved word in languages, bridge_type is better :D
>
> Since I'm typing, what are our chances of using enum fields for things
> like state, bridge_type, technologies, etc. Personally, I'd like keep
> string values out when possible and use an int / enum when I can.
>
> And /sounds, I'd rather see id changed to name, since we are using the
> filename for prompts.  This leaves us the ability to use a UUID if we
> ever added it.
>
> So, ya.  However are we going to handle feedback?  I know the we are
> in beta1, however I get the feeling we are going to see a bunch of
> feedback with the hype of Astricon.
>
> Oh and lastly, can we please do /ari/v1/bridges, please, please,
> please!  Or whatever or version number is. I really, really think we
> need the namespace in the URL.
>
> --
> Paul Belanger | PolyBeacon, Inc.
> Jabber: paul.belanger at polybeacon.com | IRC: pabelanger (Freenode)
> Github: https://github.com/pabelanger | Twitter:
> https://twitter.com/pabelanger
>
> --
> _____________________________________________________________________
> -- Bandwidth and Colocation Provided by http://www.api-digital.com --
>
> asterisk-dev mailing list
> To UNSUBSCRIBE or update options visit:
>    http://lists.digium.com/mailman/listinfo/asterisk-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20131012/1e127e63/attachment-0001.html>