756

I'm designing an HTTP-based API for an intranet app. I realize it's a pretty small concern in the grand scheme of things, but: should I use hyphens, underscores, or camelCase to delimit words in the URIs?


Here are my initial thoughts:

camelCase

  • possible issues if the server is case-insensitive
  • seems to have fairly widespread use in query string keys (http://api.example.com?**searchQuery**=...), but not in other URI parts

Hyphen

  • more aesthetically pleasing than the other alternatives
  • seems to be widely used in the path portion of the URI
  • never seen a hyphenated query string key in the wild
  • possibly better for SEO (this may be a myth)

Underscore

  • potentially easier for programming languages to handle
  • several popular APIs (Facebook, Netflix, StackExchange, etc.) are using underscores in all parts of the URI.

I'm leaning towards underscores for everything. The fact that most big players are using them is compelling (see https://stackoverflow.com/a/608458/360570).

6
  • From everything I've read, you should use hyphens, but underscores seem more easy to manage.
    – ServAce85
    Jun 8, 2012 at 23:42
  • 1
    I believe that hyphens were, at one time, better for SEO purposes. This might not be true now, but so many people have adopted it that it is more widely accepted as best practice. Underscores on the other hand may be more easy to deal with in backend programming. I use PHP, so it's much easier to use an underscore for a function name than a hyphen. camelCase may be the easiest to implement, but reading it is often difficult. Finally, I think you were right when you said that you never see a hyphenated query string in the wild. That's typically a time for camelCase.
    – ServAce85
    Jun 25, 2012 at 16:30
  • According to this question, underscore is not a valid option: stackoverflow.com/questions/3641722/…
    – wytten
    Jan 11, 2013 at 19:35
  • 2
    Possible duplicate of Are there any naming convention guidelines for REST APIs?
    – Aurora0001
    Jun 10, 2017 at 17:41
  • 1
    @wytten that question is about the scheme part of the URL. That is not what is being asked here. (Although not clear from the question title, the question post makes it clear the OP is asking about the query string part of a URL.)
    – Frans
    Jul 20, 2023 at 12:04

8 Answers 8

749

You should use hyphens in a crawlable web application URL. Why? Because the hyphen separates words (so that a search engine can index the individual words), and a hyphen is not a word character. Underscore is a word character, meaning it should be considered part of a word.

Double-click this in Chrome: camelCase
Double-click this in Chrome: under_score
Double-click this in Chrome: hyphen-ated

See how Chrome (I hear Google makes a search engine too) only thinks one of those is two words?

camelCase and underscore also require the user to use the shift key, whereas hyphenated does not.

So if you should use hyphens in a crawlable web application, why would you bother doing something different in an intranet application? One less thing to remember.

10
  • 32
    My Firefox 24 on Windows 7 thinks 'hyphen-ated' is two words. Oct 17, 2013 at 13:16
  • 10
    and it behaves the same for 'under_score'. Oct 17, 2013 at 13:23
  • 43
    any convention for the queryString, for instance ?event_id=1 or ?eventId=1??? Oct 7, 2015 at 23:21
  • 14
    @user2727195 Although URLs are case-sensitive, best practice is to use lower case wherever possible, as it removes the possibility of mistyping. Mar 8, 2016 at 12:13
  • 1
    @user2727195 also I would drop the term id from the parameter name and just have event=1 Jan 11, 2018 at 9:47
365

The standard best practice for REST APIs is to have a hyphen, not camelcase or underscores.

This comes from Mark Masse's "REST API Design Rulebook" from Oreilly.

In addition, note that Stack Overflow itself uses hyphens in the URL: .../hyphen-underscore-or-camelcase-as-word-delimiter-in-uris

As does WordPress: http://inventwithpython.com/blog/2012/03/18/how-much-math-do-i-need-to-know-to-program-not-that-much-actually

2
  • 8
    If you look at the chapter on query string guidelines in the REST API Design Rulebook, you'll notice the guidelines vary according to rule part. There's no explicit rule about casing in query strings, but you'll find that all of the examples in the section on query strings that all the keys are in camel case. Jul 28, 2015 at 19:37
  • 8
    Just FYI - "REST API Design Rulebook" was published in Oct 2011. It's possible things have changed in the past 8 years.
    – ChrisN
    Dec 3, 2019 at 16:28
43

Short Answer:

lower-cased words with a hyphen as separator

Long Answer:

What is the purpose of a URL?

If pointing to an address is the answer, then a shortened URL is also doing a good job. If we don't make it easy to read and maintain, it won't help developers and maintainers alike. They represent an entity on the server, so they must be named logically.

Google recommends using hyphens

Consider using punctuation in your URLs. The URL http://www.example.com/green-dress.html is much more useful to us than http://www.example.com/greendress.html. We recommend that you use hyphens (-) instead of underscores (_) in your URLs.

Coming from a programming background, camelCase is a popular choice for naming joint words.

But RFC 3986 defines URLs as case-sensitive for different parts of the URL. Since URLs are case sensitive, keeping it low-key (lower cased) is always safe and considered a good standard. Now that takes a camel case out of the window.

Source: https://metamug.com/article/rest-api-naming-best-practices.html#word-delimiters

32

Whilst I recommend hyphens, I shall also postulate an answer that isn't on your list:

Nothing At All

  • My company's API has URIs like /quotationrequests/, /purchaseorders/ and so on.
  • Despite you saying it was an intranet app, you listed SEO as a benefit. Google does match the pattern /foobar/ in a URL for a query of ?q=foo+bar
  • I really hope you do not consider executing a PHP call to any arbitrary string the user passes in to the address bar, as @ServAce85 suggests!
7
  • 74
    What's bad about this response is that, from an SEO perspective, there's no way for a machine to understand where one word ends and another begins, so this information is lost. It's also hard for human readers as well. It's better to have some word-level separators than nothing. May 28, 2015 at 20:46
  • 5
    @AlSweigart SEO is not relevant as this is an intranet application behind a log-in wall. May 29, 2015 at 12:17
  • 4
    I agree with @niel-mcguigan that even though this is an intranet app, if you use hyphens everywhere it's one less thing to remember. Jun 17, 2016 at 20:40
  • 2
    @DrewGoodwin Fair enough. Though do note that I said "postulate" not "recommend" :-) And domains usually do not have hyphens in them, so using them in paths is already one more thing to remember. Dec 21, 2016 at 15:07
  • 2
    it also throws all kinds of spelling errors in IDEs as mashed up words aren't able to be checked. A minor nitpick potentially but actually mispelling REST routes can lead to bugs so having the spellchecker work is actually a nice benefit. Jun 23, 2021 at 14:40
23

In general, it's not going to have enough of an impact to worry about, particularly since it's an intranet app and not a general-use Internet app. In particular, since it's intranet, SEO isn't a concern, since your intranet shouldn't be accessible to search engines. (and if it is, it isn't an intranet app).

And any framework worth it's salt either already has a default way to do this, or is fairly easy to change how it deals with multi-word URL components, so I wouldn't worry about it too much.

That said, here's how I see the various options:

Hyphen

  • The biggest danger for hyphens is that the same character (typically) is also used for subtraction and numerical negation (ie. minus or negative).
  • Hyphens feel awkward in URL components. They seem to only make sense at the end of a URL to separate words in the title of an article. Or, for example, the title of a Stack Overflow question that is added to the end of a URL for SEO and user-clarity purposes.

Underscore

  • Again, they feel wrong in URL components. They break up the flow (and beauty/simplicity) of a URL, since they essentially add a big, heavy apparent space in the middle of a clean, flowing URL.
  • They tend to blend in with underlines. If you expect your users to copy-paste your URLs into MS Word or other similar text-editing programs, or anywhere else that might pick up on a URL and style it with an underline (like links traditionally are), then you might want to avoid underscores as word separators. Particularly when printed, an underlined URL with underscores tends to look like it has spaces in it instead of underscores.

CamelCase

  • By far my favorite, since it makes the URLs seem to flow better and doesn't have any of the faults that the previous two options do.
  • Can be slightly harder to read for people that have a hard time differentiating upper-case from lower-case, but this shouldn't be much of an issue in a URL, because most "words" should be URL components and separated by a / anyways. If you find that you have a URL component that is more than 2 "words" long, you should probably try to find a better name for that concept.
  • It does have a possible issue with case sensitivity, but most platforms can be adjusted to be either case-sensitive or case-insensitive. Any it's only really an issue for 2 cases: a.) humans typing the URL in, and b.) Programmers (since we are not human) typing the URL in. Typos are always a problem, regardless of case sensitivity, so this is no different that all one case.
5
  • 24
    Disagree. Look at SO, look all wordpress sites, look at most news sites, they all use hyphens. Also camel case mixes cases, the web should be all lower case in my opinion. May 11, 2015 at 22:22
  • 5
    In my opinion, the web should be case insensitive, actually. Regarding the convention, if you follow RoR (ruby on rails) routes approach, you'd use underscores. Usually, I do so to keep it consistent accross rails generated routes and my named routes. Nevertheless, I reckon that for me dash read better than underscores.
    – rpbaltazar
    Sep 24, 2015 at 13:05
  • 1
    Perhaps they have an internal search engine in their intranet? Apr 4, 2016 at 5:50
  • 6
    Disagree. Both of your arguments against hyphens are flawed. There is no danger about negation or subtraction because we're talking about the name portion of a tuple here, you should never be functioning or evaluating the name part of a tuple for math or negation. There is also nothing awkward about using hyphens in URIs as it's a long-standing best practice used by a dearth of well-established sites. They also do not require hitting the Shift key and are treated as word boundaries by virtually everyone.
    – tpartee
    Feb 3, 2017 at 1:05
  • 7
    As far back as I can remember, hyphens have been the heavily used norm in URL's, and is definitely considered best practice in today's standards. Not using them because the feel awkward seems awkward to me. Mar 3, 2017 at 18:20
7

It is recommended to use the spinal-case (which is highlighted by RFC3986), this case is used by Google, PayPal, and other big companies.

source:- https://blog.restcase.com/5-basic-rest-api-design-guidelines/

EDIT: Although the highlight on the RFC is nowhere to be found, the recommendation on spinal case is still valid (as already noted in other answers)

2
  • 2
    Could not find the highlight in RFC3986 - can you point out in what section?
    – Mistriel
    May 20, 2021 at 16:41
  • Indeed, I also cannot find it.
    – Jivan Pal
    Jan 18, 2022 at 11:42
6

We should use hyphens in web page URLs to convince search engines to index each keyword in the URL separately.

-3

here's the best of both worlds.

I also "like" underscores, besides all your positive points about them, there is also a certain old-school style to them.

So what I do is use underscores and simply add a small rewrite rule to your Apache's .htaccess file to re-write all underscores to hyphens.

https://yoast.com/apache-rewrite-dash-underscore/

Not the answer you're looking for? Browse other questions tagged or ask your own question.