[asterisk-app-dev] Standardization of Case for ARI URIs

[Daniel Jenkins]

On Mon, Jan 20, 2014 at 8:45 PM, Paul Belanger <paul.belanger at polybeacon.com
> wrote:

> On Mon, Jan 20, 2014 at 3:24 PM, Scott Griepentrog
> <sgriepentrog at digium.com> wrote:
> >
> > While looking at https://issues.asterisk.org/jira/browse/ASTERISK-23125it is clear to me that we need standard rules for case on all ARI URI's.
>  To date, the convention has been mostly lower case, which is nominal for
> REST API's.  However, the common use of PJSIP in caps has resulted in some
> inconsistencies:
> >
> > 127.0.0.1:8088/ari/endpoints/PJSIP => list of PJSIP endpoints
> >
> > 127.0.0.1:8088/ari/endpoints/pjsip => same list of PJSIP endpoints
> >
> > 127.0.0.1:8088/ari/endpoints/PJSIP/200 => details of endpoint 200
> >
> > 127.0.0.1:8088/ari/endpoints/pjsip/200 => Endpoint not found
> >
> > For the purpose of this discussion, let's break the URI into multiple
> portions, for example:
> >
> > /ari            /endpoints        /PJSIP         /200
> > PREFIX      PATH              TECH       RESOURCE
> >
> > And in another example:
> >
> > /ari            /channels      /channelid      /operation
> > PREFIX      PATH              ID             OPERATION
> >
> > There could be different capitalization rules applied to each portion.
>  For example, in PJSIP it is completely possible to have one endpoint
> "foobar" and another "FOOBAR" -- thus we can presume that any resource
> portion MUST be case sensitive.  Similarly, a channel ID must be case
> sensitive.
> >
> > The TECH portion is currently exhibiting case insensitivity in one case
> (list of endpoints) and case sensitivity in another (endpoint details).
> >
> > The PATH portion is currently case sensitive (Endpoints or ENDPOINTS
> results in error).
> >
> > And finally the PREFIX is case insensitive (ArI and aRi both work).
> >
> >
> > This way leads madness, and I propose we put a stop to it now.
> >
> >
> > There are many possible variations on how to solve this, but I recommend
> the following, and invite other suggestions.  I believe that having
> different rules for different portions of the URI will lead to confusion.
>  Since there is already a requirement that identifiers and resources are
> case sensitive, I recommend standardizing on case sensitive for the entire
> URI.  Other than the TECH name which historically in Asterisk has been
> CAPS, all portions should be lower case where possible to meet current web
> API norms.  In detail:
> >
> > PREFIX: case sensitive, always lower case
> >
> > PATH: case sensitive, always lower case
> >
> > TECH: case sensitive, case determined by actual technology name,
> convention is all UPPERCASE
> >
> > RESOURCE: case sensitive, must match actual configured value.
> >
> > ID: case sensitive, must match actual identifier
> >
> > OPERATION: case sensitive, always lower case
> >
> > This recommendation is compatible with the vast majority of existing
> documentation, and will require very little code change to implement.
> >
> >
> > tl;dr: make TECH the only uppercase URI portion by convention,
> everything else is lower case except IDs and resource names, and EVERYTHING
> is case sensitive.
> >
> Personally, I prefer everything to be lower case when possible.  So,
> things like TECH, if PJSIP, pjsip, PjSiP, are all valid inside
> asterisk, lets round down to pjsip.  However, if ENDPOINT is case
> sensitive in Asterisk, then expect the end user to enter it as such.
>
> So using your example above:
>
> 127.0.0.1:8088/ari/endpoints/pjsip/200
>
> or
>
> 127.0.0.1:8088/ari/endpoints/pjsip/FooBar
>
> or
>
> 127.0.0.1:8088/ari/endpoints/pjsip/foobar
>
> All return different endpoints.
>
> Additionally, have we even considered embedding the actually resource
> URL when we list an object in the return result? Then Asterisk can
> tell the user exactly how to get a specific item in the list.
>
> For example, we create a links: [] object, that would list the actual
> URI for said item.
>
> --
> Paul Belanger | PolyBeacon, Inc.
> Jabber: paul.belanger at polybeacon.com | IRC: pabelanger (Freenode)
> Github: https://github.com/pabelanger | Twitter:
> https://twitter.com/pabelanger
>
> _______________________________________________
> asterisk-app-dev mailing list
> asterisk-app-dev at lists.digium.com
> http://lists.digium.com/cgi-bin/mailman/listinfo/asterisk-app-dev


+1 to everything Paul said
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-app-dev/attachments/20140120/0394304c/attachment-0001.html>