<div dir="ltr">On Mon, Oct 14, 2013 at 6:51 PM, David M. Lee <span dir="ltr"><<a href="mailto:dlee@digium.com" target="_blank">dlee@digium.com</a>></span> wrote:<br><div class="gmail_extra"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class="im"><br>
On Oct 14, 2013, at 11:23 AM, Paul Belanger <<a href="mailto:paul.belanger@polybeacon.com">paul.belanger@polybeacon.com</a>> wrote:<br>
<br>
> One thing I have noticed, it objects in the ARI don't seem to have a consistent behaviour when it comes to the 'id' parameter.<br>
><br>
> Most will default to 'id' as the primary key, however a few are just missing this or using a different field for it (name). Seems trivial right now, but already building out a lib atop of ARI you can quickly see out you need to add additional layers of logic to check if ID exists or name, etc.<br>
<br>
</div><snip/><br>
<div class="im"><br>
> I don't want to list them all, but I think you get the idea. Thoughts?<br>
<br>
</div>Given the naming convention I used, Sound's 'id' field probably should<br>
have been 'name'.<br>
<br>
The original intention was to model the objects as they exist in the<br>
system. Some objects have an id, but no name (like Bridge). Some<br>
objects have a name, but no id (like Recording), some have both (like<br>
Channel), and some are just weird (like Endpoint).<br>
<br>
I would think that the library would have specific code for the<br>
different domain-objects, and that would be the place to handle type<br>
differences (like named vs. id'ed). But there is a subtle difference<br>
between the two: name carries meaning, whereas an id is opaque (you<br>
should never care about the format or content of an id; just its<br>
value).<br></blockquote><div><br></div><div>Not too sure about this, each library shouldn't need to understand these kinds of scenarios, the API payload should be as descriptive as it can (within reason) - but I understand there's going to be overlaps, what's the decision in this instance? Both id and name seem either wrong or limiting for the future...</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
While we could manufacture id's for objects that only carry names,<br>
keeping the id's consistent would be a challenge. We'd have to store<br>
them somewhere. And the manufactured id is more likely to change for<br>
silly reasons, which would cause all sorts of headaches.<br>
<div class="im"><br>
> Well, another issue I didn't mention is the mixture of camelCase and snake_case within the parameters. At best, it is not consistent. Personally, I prefer snake_case, but that is a discussion point. Morst importantly I think, is we pick one and stick to it.<br>
<br>
</div>The Swagger convention is camelCase, so the parameters are all<br>
camelCase.<br>
<br>
Asterisk, however, is snake_case, and the models are based on that.<br>
That is an unfortunate inconsistency.<br>
<br>
At the time, I was okay with it. Now I'm regretting the decision. But<br>
since I would vote for camelCase, we might have a fight on our hands.<br></blockquote><div><br></div><div>I prefer camelCase - and this is what jshint's standard is too - but I get people from different backgrounds are going to have different opinions, as long as it's consistent I'm really not too bothered though</div>
<div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class="im"><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>
>>><br>
>>> Swagger supports enums, although I'll defer to David on all the pros and<br>
>>> cons of using enums instead of more basic data types (for example, Python<br>
>>> doesn't support enums until 3.4, so there may be some finicky aspects to<br>
>>> adopting it).<br>
<br>
</div>The enums provided in Swagger are just restricted values on the string<br>
type, which we use when appropriate. We avoid them when the list is<br>
dynamic, like bridging technology.<br>
<br>
It's still a string over the wire; a client library can use enums<br>
based on the restricted values if it wants to.<br></blockquote><div><br></div><div>Can someone give me an example of how this would change?</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class="im"><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>
>>><br>
>>> It isn't always a filename (or at least, I hope it won't always be soon!)<br>
>>> We definitely want the ability for a URI to a remote resource to be able to<br>
>>> be specified instead of a sound file located on the Asterisk system.<br>
>>> Renaming it to filename here again makes that a bit more confusing, rather<br>
>>> than clarifying.<br>
>>><br>
>><br>
>> I'd agree in changing id to something else, but not name/filename etc -<br>
>> maybe resource as the file would be a resource, a remote uri would be a<br>
>> resource etc - these would still be identifiers<br>
<br>
</div>I'd be fine with 'name' since it's simply the name of the sound<br>
(hello-world, beep, tt-monkeys) and doesn't imply filename at all.<br></blockquote><div><br></div><div>But then name doesn't really imply that it could be a remote url etc, which it could be at a future date...?</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class="im"><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>
>>>><br>
>>><br>
>>> While I'm not sure we want the version number to be explicitly in the<br>
>>> path, I do think we need versioning in ARI in some fashion, particularly if<br>
>>> we start introducing breaking changes into the REST API mid-stream.<br>
>>><br>
>>><br>
>> PLEASE do not do this, versioning shouldn't belong in a URL - as it doesn't<br>
>> describe the resource. In my view, if you require a specific version of the<br>
>> ARI, this should be done with headers - send in an "Accept-Version" header<br>
>> which is a semver style "~2" for example<br>
>><br>
>> This way, you get the most up to date API if you don't ask for a specific<br>
>> version.<br>
>><br>
>> The Restify project in npm does this (along with many many others) - take a<br>
>> look at how they deal with requesting of versions here:<br>
>> <a href="http://mcavage.me/node-restify/" target="_blank">http://mcavage.me/node-restify/</a><br>
<br>
</div>I like the Accept-Version approach. I started writing a wiki page<br>
about versioning, but then some distractions happened (like actually<br>
getting the API to work :-), but I'll be sure to get back on that.<br>
<a href="https://wiki.asterisk.org/wiki/x/WwCUAQ" target="_blank">https://wiki.asterisk.org/wiki/x/WwCUAQ</a></blockquote><div><br></div><div><br></div><div>Cool!</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
<br>
--<br>
David M. Lee<br>
Digium, Inc. | Software Developer<br>
<div class="im">445 Jan Davis Drive NW - Huntsville, AL 35806 - USA<br>
</div>Check us out at: <a href="http://www.digium.com" target="_blank">www.digium.com</a> & <a href="http://www.asterisk.org" target="_blank">www.asterisk.org</a><br>
<div class="HOEnZb"><div class="h5"><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></div></div></blockquote><div><br></div><div><br></div><div>Dan </div></div><br>
</div></div>