[asterisk-dev] ARI feedback
Paul Belanger
paul.belanger at polybeacon.com
Mon Oct 14 11:23:45 CDT 2013
On 13-10-13 05:39 PM, Dan Jenkins, HolidayExtras.com wrote:
> On 13 October 2013 16:22, Matthew Jordan <mjordan at digium.com> wrote:
>
>>
>> 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?
>>>
>>
>> The policy [1] for Asterisk 12 is that, once released, new features can be
>> added to the released branch subject to the following constraints:
>>
>> 1. 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:
>> 1. The new SIP stack based on PJSIP
>> 2. The core APIs facilitating the new external APIs, that is, the
>> Bridging API and the Stasis Message Bus
>> 3. External facing APIs (AMI, ARI, AGI)
>> 2. 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.
>> 3. 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.
>>
>>
>> [1]
>> https://wiki.asterisk.org/wiki/display/AST/Software+Configuration+Management+Policies
>>
>> So, what about changes to an API once it has been included in Asterisk 12?
>>
>> 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.
>>
>> 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.
>>
>>
>>>
>>> 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.
>>>
>>
>> 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.
>>
>>
> Agree with this, if the id is a uuid / unique id / random string and it's
> documented as such that's fine, and fine to label it as an id, as it is an
> "id" in that context, id may be a uuid but the key should be id.
>
Fair enough, it is a matter of personal preference. 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.
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.
ID examples:
Bridge {
id,
...
}
Channel {
id,
...
}
(This is actually the filename, but wrapped as an ID)
Sound {
id,
...
}
Name examples:
Application {
name,
...
}
StoredRecording {
name,
...
}
LiveRecording {
name,
...
}
I don't want to list them all, but I think you get the idea. Thoughts?
>
>>
>>> 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
>>>
>>
>> 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.
>>
>
> This seems a little crazy but know how difficult it is to keep consistency
> in an API, I fight this battle every day - do we want the url params to be
> consistent and so just have it as type? But then you want the response to
> be descriptive. From my point of view it should just be type (I'm not a fan
> of putting rules into your api because of reserved words that however many
> languages may use - you'd be continuously looking to make sure you weren't
> doing something wrong for one lang but something ok in another)
>
> In the parameter it's type and so consistent across multiple requests and
> in the response, the response is a bridge object as such and so should just
> be type, in this response there should be nothing prefixed with "bridge" as
> it's described by your URI
>
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.
>
>>
>>
>>>
>>> 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.
>>>
>>
>> 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).
>>
>> 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.
>>
>
> I'd implore you not to go down this route, strings are your friends in
> keeping your API descriptive without having to reference other
> documentation, your API shouldn't require too much referring to
> documentation.
>
>
>>
>>
>>>
>>> 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.
>>>
>>
>> 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.
>>
>
> I'd agree in changing id to something else, but not name/filename etc -
> maybe resource as the file would be a resource, a remote uri would be a
> resource etc - these would still be identifiers
>
>
>>
>>
>>>
>>> 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.
>>>
>>
>> Mailing list to be created on Monday :-)
>>
>
> WOOHOO!
>
>
>>
>>
>>>
>>> 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.
>>>
>>
>> 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.
>>
>>
> PLEASE do not do this, versioning shouldn't belong in a URL - as it doesn't
> describe the resource. In my view, if you require a specific version of the
> ARI, this should be done with headers - send in an "Accept-Version" header
> which is a semver style "~2" for example
>
> This way, you get the most up to date API if you don't ask for a specific
> version.
>
> The Restify project in npm does this (along with many many others) - take a
> look at how they deal with requesting of versions here:
> http://mcavage.me/node-restify/
>
> Matt
>>
>> --
>> Matthew Jordan
>> Digium, Inc. | Engineering Manager
>> 445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
>> Check us out at: http://digium.com & http://asterisk.org
>>
>> --
>> _____________________________________________________________________
>> -- 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
>>
>
>
> Dan
>
>
>
--
Paul Belanger | PolyBeacon, Inc.
Jabber: paul.belanger at polybeacon.com | IRC: pabelanger (Freenode)
Github: https://github.com/pabelanger | Twitter:
https://twitter.com/pabelanger
More information about the asterisk-dev
mailing list