<div dir="ltr"><br><div class="gmail_extra"><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:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style: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></blockquote><div><br></div><div style>The policy [1] for Asterisk 12 is that, once released, new features can be added to the released branch subject to the following constraints:</div>
<div><ol style="margin:10px 0px 0px;color:rgb(51,51,51);font-family:'Helvetica Neue',Helvetica,Arial,sans-serif;font-size:13.63636302947998px;line-height:18.18181800842285px;background-color:rgb(255,253,246)"><li>
The new feature or improvement must be made in relation to the goals of Asterisk 12; namely, the improvement or new feature must be in one of the following areas:<ol style="margin:0px;list-style-type:lower-alpha"><li>The new SIP stack based on PJSIP</li>
<li>The core APIs facilitating the new external APIs, that is, the Bridging API and the Stasis Message Bus</li><li>External facing APIs (AMI, ARI, AGI)</li></ol></li><li>The new feature or improvement must have thorough unit testing and/or functional testing provided by the Asterisk Test Suite. No new features or improvements without test coverage will be allowed midstream.</li>
<li>Any new feature or improvement must go through the normal Asterisk new feature process. This includes a thorough code review on Review Board. If you have questions about whether or not the new feature or improvement will be accepted or is appropriate, please ask in #asterisk-dev or the asterisk-dev mailing list before development.</li>
</ol></div><div><br></div><div>[1] <a href="https://wiki.asterisk.org/wiki/display/AST/Software+Configuration+Management+Policies">https://wiki.asterisk.org/wiki/display/AST/Software+Configuration+Management+Policies</a></div>
<div><br></div><div style>So, what about changes to an API once it has been included in Asterisk 12?</div><div style><br></div><div style>The goal for this policy is to allow everyone to continue their engineering efforts throughout Asterisk 12 such that, once Asterisk 13 is released, it is a smooth transition from the standard release to the LTS. I think we have to be cautious about re-doing work that is already done - if we make a lot of breaking changes on an already released portion of the API, we're actually working contrary to the goal of this policy. We're making it harder for people to engineer on top of Asterisk, not easier.</div>
<div><br></div><div style>I don't want to go so far as to say that we should never change an API once we've released it in Asterisk 12 - I think we're all in agreement after AstriDevCon that the unanimous "no new things" in Asterisk has been more limiting than everyone would like - but I do think we should all approach breaking changes very conservatively, and only propose such changes when the reason is sufficiently important.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<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></blockquote><div><br></div><div style>I disagree on this one. In general, the type should not be reflected by the parameter name - the type restricts how the parameter can be used; the parameter name describes its purpose. It can also tie its usage to internal implementation details in Asterisk. Say, for example, we discover that generating a UUID has a large enough performance impact that we'd rather generate the unique ID in a manner similar to a channel's unique ID, i.e., a unique string given by asterisk.conf coupled with a timestamp. Both could be considered unique IDs, but if the field name is UUID instead of 'id' or 'unique_id', we've put ourselves in a situation where our options are to either confuse the API further or live with the performance penalty.</div>
<div style><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<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></blockquote><div><br></div><div style>Consistency is a good thing, and 'type' as a parameter name isn't a favorite of mine either. We should probably discuss changing this one further, particularly if 'type' and 'bridge_type' are guaranteed to always be identical.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<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></blockquote><div><br></div><div style>Swagger supports enums, although I'll defer to David on all the pros and cons of using enums instead of more basic data types (for example, Python doesn't support enums until 3.4, so there may be some finicky aspects to adopting it).</div>
<div style><br></div><div style>One thing that should probably not be supported by an enum type are any parameters that reflect facilities in Asterisk provided by loadable modules. bridge_type is one of these - the Bridging Framework itself does not provide any mixing technologies. Said mixing technologies are actually provided by dynamically loaded modules that plug into the Framework. If we make this an enum with only the values currently supported by the loadable modules delivered with Asterisk, it prevents someone from writing a new bridge mixing technology and easily using it from ARI.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<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></blockquote><div><br></div><div style>It isn't always a filename (or at least, I hope it won't always be soon!) We definitely want the ability for a URI to a remote resource to be able to be specified instead of a sound file located on the Asterisk system. Renaming it to filename here again makes that a bit more confusing, rather than clarifying.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<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></blockquote><div><br></div><div style>Mailing list to be created on Monday :-)</div><div style> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">

<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></blockquote><div><br></div><div style>While I'm not sure we want the version number to be explicitly in the path, I do think we need versioning in ARI in some fashion, particularly if we start introducing breaking changes into the REST API mid-stream.</div>
<div style><br></div><div style>Matt</div></div><div><br></div>-- <br><div dir="ltr"><div>Matthew Jordan<br></div><div>Digium, Inc. | Engineering Manager</div><div>445 Jan Davis Drive NW - Huntsville, AL 35806 - USA</div>
<div>Check us out at: <a href="http://digium.com" target="_blank">http://digium.com</a> & <a href="http://asterisk.org" target="_blank">http://asterisk.org</a></div></div>
</div></div>