microsoft
URL path camelCase vs underscore vs dash etc.
It would be great if the standards document expressed a clear opinion on how multiple words should be concatenated in URL path segments.
For example:
https://api.contoso.com/v1.0/pullRequests https://api.contoso.com/v1.0/pull-requests https://api.contoso.com/v1.0/pull_requests https://api.contoso.com/v1.0/pullrequests
I don't think we currently have guidance for multiple words in URL path segments but I believe we have one tangentially related statement around multiple words JSON property names in 7.10 Response Formats:
JSON property names SHOULD be camelCased.
This part uses dashes. In addition to that, we could also take the repository name/link api-guidelines as a hint to use dashes. :smile:
LOL on the repo name. Yes, your example is pretty unfortunate. We certainly don't recommend that, but that one probably has to be grandfathered in for historical reasons. I should add that exception to the naming guidelines proposal in the topic branch of this repo. I believe we would recommend camelCased for explanatory purposes, but that services should be case-insensitive for any terms which they provide and character-for-character exact comparisons for any user-provided data. So in the original query,
https://api.contoso.com/v1.0/pullRequests
Note that this will break some particular word combinations. pullRequests will be handled the same as pulLrequests. (which doesn't makes sense in this example, but CAN make sense in other examples)
Our point is that we would never want anyone to ship an API from Microsoft that had those two combinations (or two combinations that did make sense) at the same place in URL space where they could possibly conflict because the potential for user error would be simply too high. We're trying to optimize for ease of use for the service consumer, over flexibility for the service builder.
@scriby, a PR would be great to address this with a camelCase, but case insensitive recommendation at the appropriate spot.
Gone through many documents but not able to conclude. So started looking into other companies problems with the URLs and what they are doing to resolve it. Found major problems of URL is case sensitive issue. So option one is on the least priority and option four is not so readable. So go with the option two or three. Most of the companies like google, PayPal & other big companies are using spinal-case for the url. https://api.contoso.com/v1.0/pull-requests
Personally I rather use snake_case or camelCase as select with mouse button is easier, being spinal-case the worst case scenario for that, and option 4 is the worst choice overall. Would say camelCase might be risky for some systems that are not case sensitive although I don't think it should ever be a problem as why would some1 distinguish endpoints with Upper case, would be just bad practive.
Snake_case is the most used format and standard in C, no disadvantages comparing to spinal-case, some of the tech folks in this bigger companies just go over their heads to justify their existence, trying to make spinal-case a standard is just annoying to devs that want to use copy paste efficiently, the aesthetic improvement for non programmings is of really low importance comparing to just this issue that can bring actual bugs by bad copy past or that is not possible to use it in some languages. Disgusting this as extended to GCP naming rules of some objects and forced by not accepting the under_score.
Agree with @RBhalala. Spinal-case is more suitable option. It is widely used.
