[asterisk-dev] ARI feedback

Sun Oct 13 16:39:20 CDT 2013

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.

>
>> 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

>
>
>>
>> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20131013/9a22de82/attachment-0001.html>