<div dir="ltr">+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:<div>
<div><br></div><div>I have an endpoint for Bob and we use URI versioning</div><div><br></div><div>GET /v1/endpoints/sip/bob</div><div><br></div><div>then I update some of my Asterisk servers to v2</div><div><br></div><div>
GET /v2/endpoints/sip/bob</div><div><br></div><div>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.  </div>
<div><br></div><div>It seems that using content-type for versioning would be a cleaner solution. </div><div><br>I'm parroting / paraphrasing Peter Williams <a href="http://barelyenough.org/blog/2008/05/versioning-rest-web-services/">http://barelyenough.org/blog/2008/05/versioning-rest-web-services/</a></div>
<div><br></div><div>Note that Github used URI versioning in v1 and v2 of its API, but updated to content-type in v3:</div><div><br></div><div><a href="http://developer.github.com/v3/media/">http://developer.github.com/v3/media/</a><br>
</div><div><br></div><div>I suspect other popular APIs will follow suit. </div></div></div><div class="gmail_extra"><br clear="all"><div><div dir="ltr"><b>Billy Chia</b><div>Digium, Inc. | Product Marketing Manager</div><div>
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA</div><div>direct: +1 256-428-6099</div><div><b>Check us out at</b>: <a href="http://www.digium.com/" target="_blank"><span>www.digium.com</span></a> & <a href="http://www.asterisk.org/" target="_blank"><span>www.asterisk.org</span></a></div>
</div></div>
<br><br><div class="gmail_quote">On Sat, Oct 12, 2013 at 5:13 PM, Paul Belanger <span dir="ltr"><<a href="mailto:paul.belanger@polybeacon.com" target="_blank">paul.belanger@polybeacon.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Back from Astricon and already hacking our queue app to hook into ARI,<br>
however I'm curious about how we are going to handle feedback of the<br>
ARI APIs? How locked down are we on things?<br>
<br>
For example, it would be nice when we pass back a UUID (eg: bridging)<br>
that we named it uuid, not id.  I know it is trivial, but seems to<br>
help me remember the format better.<br>
<br>
Another example, again in bridging is on POST /bridges it expect a<br>
parameter as 'type' however the API returns 'bridge_type', again, it<br>
would be nice to have them both the same.  And since 'type' is usually<br>
a reserved word in languages, bridge_type is better :D<br>
<br>
Since I'm typing, what are our chances of using enum fields for things<br>
like state, bridge_type, technologies, etc. Personally, I'd like keep<br>
string values out when possible and use an int / enum when I can.<br>
<br>
And /sounds, I'd rather see id changed to name, since we are using the<br>
filename for prompts.  This leaves us the ability to use a UUID if we<br>
ever added it.<br>
<br>
So, ya.  However are we going to handle feedback?  I know the we are<br>
in beta1, however I get the feeling we are going to see a bunch of<br>
feedback with the hype of Astricon.<br>
<br>
Oh and lastly, can we please do /ari/v1/bridges, please, please,<br>
please!  Or whatever or version number is. I really, really think we<br>
need the namespace in the URL.<br>
<span class="HOEnZb"><font color="#888888"><br>
--<br>
Paul Belanger | PolyBeacon, Inc.<br>
Jabber: <a href="mailto:paul.belanger@polybeacon.com">paul.belanger@polybeacon.com</a> | IRC: pabelanger (Freenode)<br>
Github: <a href="https://github.com/pabelanger" target="_blank">https://github.com/pabelanger</a> | Twitter: <a href="https://twitter.com/pabelanger" target="_blank">https://twitter.com/pabelanger</a><br>
<br>
--<br>
_____________________________________________________________________<br>
-- Bandwidth and Colocation Provided by <a href="http://www.api-digital.com" target="_blank">http://www.api-digital.com</a> --<br>
<br>
asterisk-dev mailing list<br>
To UNSUBSCRIBE or update options visit:<br>
   <a href="http://lists.digium.com/mailman/listinfo/asterisk-dev" target="_blank">http://lists.digium.com/mailman/listinfo/asterisk-dev</a><br>
</font></span></blockquote></div><br></div>