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.


  • sockdevs

    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, 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.



  • This stuff's for computers to interact with each other though. Does it matter?


  • sockdevs

    programmer's gotta type it at some point.

    it's a stylistic preference, nothing critical. Consistency in naming scheme is more important.



  • @accalia said:

    programmer's gotta type it at some point.

    Like once.

    @accalia said:

    Consistency in naming scheme is more important.

    True.


  • Discourse touched me in a no-no place

    @loopback0 said:

    Like once.

    Theoretically yes. Practically… :no_mouth:



  • @dkf said:

    @loopback0 said:
    Like once.

    Theoretically yes. Practically… :no_mouth:

    Well yeaaaahhhh. But that's the same whichever format you use.



  • @calmh said:

    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.


  • Discourse touched me in a no-no place

    @accalia said:

    programmer's fingers gotta type it at some point.

    FTFY. It was making me grit my teeth.


  • Discourse touched me in a no-no place

    @loopback0 said:

    Go with /api/widdlyfidgets just to fuck with consumers of the API.

    He's not writing a Discourse mod, probably.


  • sockdevs

    @FrostCat said:

    @accalia said:
    programmer's fingerspaws gotta type it at some point.

    FTFY. It was making me grit my teeth.

    FTFTFYFY



  • /api/Raymond-Luxury_Yacht


  • Discourse touched me in a no-no place

    @accalia said:

    paws

    What do you call the individual fingers of paws, eh? Or do you type with the central pad like a non-touch-typist?


  • Discourse touched me in a no-no place

    @mott555 said:

    /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:

    1. 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
    2. 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.



  • @FrostCat said:

    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?



  • @Dragoon said:

    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.


  • Discourse touched me in a no-no place

    @tar said:

    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.



  • @FrostCat said:

    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...


  • Discourse touched me in a no-no place

    @tar said:

    perfectly valid

    Well, normally, but considering the source, I think we can assume that wasn't what was going on here.



  • @FrostCat said:

    considering the source,

    Stopped clocks et al...


  • Discourse touched me in a no-no place

    @tar said:

    Stopped clocks et al...

    No, I meant "it was almost certainly a typo as opposed to anything else, coming from typed it."



  • @FrostCat said:

    No, I meant "it was almost certainly a typo as opposed to anything else, coming from typed it."

    Did you accidentally a word?



  • @FrostCat said:

    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.


  • Discourse touched me in a no-no place

    @loopback0 said:

    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.


  • sockdevs

    @FrostCat said:

    Well, we all know that @accalia s are catching...

    TIL that I am a VTI


  • Discourse touched me in a no-no place

    @accalia said:

    TIL

    I'm pretty sure it's come up before. So to speak.



  • @FrostCat said:

    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.


  • Discourse touched me in a no-no place

    @anonymous234 said:

    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 normal widgets 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.



  • @accalia said:

    VTI

    TIL that Disorder starts with I.



  • @svieira said:

    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.

    @apapadimoulis said:

    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. :-)

    @loose said:

    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.



  • @apapadimoulis said:

    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 :rofl:



  • @accalia said:

    TIL that I am a VTI

    STI or
    VTTI

    Some FTFY options :)



  • @loose said:

    This is sarcasm, right?

    No, of course it's not sarcasm.


  • Discourse touched me in a no-no place

    @tar said:

    @loose said:
    This is sarcasm, right?

    No, of course it's not sarcasm.

    Wait--is that sarcasm?

    Ok. Carry on.


  • Discourse touched me in a no-no place

    Feature request: sarcasm tags


Log in to reply
 

Looks like your connection to What the Daily WTF? was lost, please wait while we try to reconnect.