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?
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
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
_______________________________________________ asterisk-app-dev mailing list asterisk-app-dev@xxxxxxxxxxxxxxxx http://lists.digium.com/cgi-bin/mailman/listinfo/asterisk-app-dev
