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

[Paul Belanger]

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