[asterisk-dev] ARI feedback

[Matthew Jordan]

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.


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


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


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


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


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

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