Nitpicky API naming survey
-
I'm making a REST-like API. So far, all my resource names were one word. But now I have to add a two word resource. Let's call it "fiddly widgets".
My question is, what naming convention is the "best"?
[Poll]
- /api/fiddly-widgets
- /api/fiddly_widgets
- /api/fiddlywidgets
- /api/fiddly%20widgets
- Just force it to one word, it's worth the effort
[/Poll]
Yeah, yeah, nitpicky. But I just KNOW if I pick the wrong one, it will annoy me every time I see it.
My primary concerns are how "webby" it looks, GUI support (eg. double click select) and readability. The first 3 choices each get about the same aggregate score on these 3 scales, which is why I'm stuck picking between them.
-
stylistically i like the underscore separation.
It prevents tyhe brain blurring the words together, which in the hands of a developer could mean that very bad words indeed can be read because we're bad at naming things.
-
What data are you shuffling? If for example JSON with camel cased keys, use
/api/fiddlyWidgets
, otherwisefiddly_widgets
if you normally use underscores in keys or parameters or whatever. If that doesn't apply because all the other parts of the API are binary or something, go with whatever... Consistency wins.
-
This stuff's for computers to interact with each other though. Does it matter?
-
programmer's gotta type it at some point.
it's a stylistic preference, nothing critical. Consistency in naming scheme is more important.
-
programmer's gotta type it at some point.
Like once.
Consistency in naming scheme is more important.
True.
-
-
@loopback0 said:
Like once.
Theoretically yes. Practically…
Well yeaaaahhhh. But that's the same whichever format you use.
-
What data are you shuffling? If for example JSON with camel cased keys, use /api/fiddlyWidgets, otherwise fiddly_widgets if you normally use underscores in keys or parameters or whatever. If that doesn't apply because all the other parts of the API are binary or something, go with whatever... Consistency wins.
I do use camelCase all over the place, but
camelCase
in API-s is IMO super duper fugly.Also, why would the layout of my API be determined by the structure of JSON payloads? These two feel like completely separate concerns.
-
It's your choice. But to me it's just two parts of the same API. Since you have nothing else to decide by, being consistent in the external API won't kill you.
That is, if you get back the reference
{... "fiddlyWidget": 42}
from somewhere, it makes more sense to me to fetch that from/rest/fiddlyWidgets/42
than the underscored version. Why have two spellings of the same concept in the same API?
-
Go with
/api/widdlyfidgets
just to fuck with consumers of the API.
-
programmer's fingers gotta type it at some point.
FTFY. It was making me grit my teeth.
-
Go with /api/widdlyfidgets just to fuck with consumers of the API.
He's not writing a Discourse mod, probably.
-
@accalia said:
programmer's
fingerspaws gotta type it at some point.FTFY. It was making me grit my teeth.
FTFTFYFY
-
/api/Raymond-Luxury_Yacht
-
paws
What do you call the individual fingers of paws, eh? Or do you type with the central pad like a non-touch-typist?
-
/api/Raymond-Luxury_Yacht
Really, one of those words needs to be in lower case, though. Preferably not the first one, either.
-
I hate camel case, SomeoneAlwaysDecidesToMakeObnoxiouslyLongNamesInItThatAreJustPlainHardToReadAndProvideNoUsefulInformation.
-
Because I have an underscore in my main personal email address (it was a good idea at the time and it worked), I have become very "sensitive" about it in recent years. The two main reasons are:
- A lot of "smart" interfaces don't allow it - not an issue here and now but maybe in the future when UIs start being "serious" about typed in URLs
- Quite often the "_" is "lost" in the "rendering" making look like a space.
Obviously camel case in any of its incarnations are out of the question, so there really is not any choice. Of course you could go with concatenating the "words" but sooner or later you are going to have some "interesting" URLs on your server. The other unspoken an obvious issue is that the URL will eventually be a "path". So there is that limitation; which could be mitigated with URL mapping stuff - by why create work?
-
I prefer dashes. Even Scheme supports using dashes in variable names. Underscores just look super ugly to me.
-
t was making me grit my teeth.
You do realize that has is as legitimate an expansion of 's as is, uh, is?
Filed under: is this question rhetorical?
-
SomeoneAlwaysDecidesToMakeObnoxiouslyLongNamesInItThatAreJustPlainHardToReadAndProvideNoUsefulInformation
but_underscores_can_also_be_used_to_the_same_devastating_effect_if_not_more_so_due_to_the_repeated_insertion_of_underscores_
-
Very_true_but_I_still_find_it_easier_to_read.
-
My preference is for
ClassName.method_name()
so I think they both have their place.Meanwhile, over at ontopic, I think
/lower-case-hypen-or-minus
is probably the best format for an endpoint, for raisins of URL compatibility.
-
You do realize that has is as legitimate an expansion of 's as is, uh, is?
Are you the kind of yokel, like @polygeekery, who would say "something needs done" instead of the correct way of saying it? Because that's what reading that as "programmer has' is.
-
Are you the kind of yokel...
Of course, but "programmer's gotta X" reads like a perfectly valid, if informal rendering of "The programmer has got to X" to me...
-
perfectly valid
Well, normally, but considering the source, I think we can assume that wasn't what was going on here.
-
-
Stopped clocks et al...
No, I meant "it was almost certainly a typo as opposed to anything else, coming from typed it."
-
No, I meant "it was almost certainly a typo as opposed to anything else, coming from typed it."
Did you accidentally a word?
-
it was almost certainly a typo as opposed to anything else
I would've assumed that a typo would've resulted in a spellar/gramming error, though.
-
Did you accidentally a word?
Well, we all know that @accalia s are catching... the missing word was "who". I had originally written that in a more grammatically-tortured way, and guess I lost the word when trying to rewrite it.
-
-
-
Well, we all know that @accalia s are catching...
The Aussies know how to control things spreading from foxes.
-
Hey, if spaces are OK in file names, why aren't they OK in URLs? What's the big difference? You'll have to put it in double quotes anyway.
-
Hey, if spaces are OK in file names, why aren't they OK in URLs?
Some dipshit said so.
-
I vote
none of the above
. Use matrix parameters to define a sub-type of your normalwidgets
resource, like Tim Berners-Lee <sotto>(but not Roy Fielding)</sotto> intended:GET /api/widgets;type=fiddly
But don't go (<sotto>too</sotto>) crazy about the purity of your endpoints.
-
Just follow the path of other RESTFUL API designers: don't allow the business requirements to sully the purity of your model.
If resources can't be described in a single word, then you're Doing It Wrong. Try a thesaurus. If that doesn't work, then simply create a new word. Eventually it will catch on, and your model will remain pure.
-
-
I vote none of the above. Use matrix parameters to define a sub-type of your normal widgets resource, like Tim Berners-Lee (but not Roy Fielding) intended:
GET /api/widgets;type=fiddly
But don't go (too) crazy about the purity of your endpoints.
Interesting. But no.
Just follow the path of other RESTFUL API designers: don't allow the business requirements to sully the purity of your model.
If resources can't be described in a single word, then you're Doing It Wrong. Try a thesaurus. If that doesn't work, then simply create a new word. Eventually it will catch on, and your model will remain pure.
Tempting. But no. :-)
Because I have an underscore in my main personal email address (it was a good idea at the time and it worked), I have become very "sensitive" about it in recent years. The two main reasons are:
A lot of "smart" interfaces don't allow it - not an issue here and now but maybe in the future when UIs start being "serious" about typed in URLs
Quite often the "_" is "lost" in the "rendering" making look like a space.Obviously camel case in any of its incarnations are out of the question, so there really is not any choice. Of course you could go with concatenating the "words" but sooner or later you are going to have some "interesting" URLs on your server. The other unspoken an obvious issue is that the URL will eventually be a "path". So there is that limitation; which could be mitigated with URL mapping stuff - by why create work?
It was between @accalia's underscores and this, but in the end, I think I'll go with dashes.
I personally prefer underscores, especially since some editor will happily treat dashes as word-boundaries (so you can't easily select the entire URL by double-clicking, for example). But standards and future-proofing are more important.
-
Just follow the path of other RESTFUL API designers: don't allow the business requirements to sully the purity of your model.
If resources can't be described in a single word, then you're Doing It Wrong. Try a thesaurus. If that doesn't work, then simply create a new word. Eventually it will catch on, and your model will remain pure.
Seriously? This is sarcasm, right?
On a more humorous note: If the resources were to have single word descriptive name, I can imagine a situation where all the resources will the same (or very similar) name. On the plus side they would be easier to remember as they would not be more than 4 or 6 characters long
-
-
-
@loose said:
This is sarcasm, right?
No, of course it's not sarcasm.
Wait--is that sarcasm?
Ok. Carry on.
-
Feature request: sarcasm tags