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

[Scott Griepentrog]

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.


What say you?

-- 
[image: Digium logo]
Scott Griepentrog
Digium, Inc · Software Developer
445 Jan Davis Drive NW · Huntsville, AL 35806 · US
direct/fax: +1 256 428 6239 · mobile: +1 317 507 4029
Check us out at: http://digium.com · http://asterisk.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-app-dev/attachments/20140120/ee0a7328/attachment.html>