Are there any naming convention guidelines for REST APIs?

Question

When creating REST APIs, are there any guidelines or defacto standards for naming conventions within the API (eg: URL endpoint path components, querystring parameters)? Are camel caps the norm, or underscores? others?

For example:

api.service.com/helloWorld/userId/x

or

api.service.com/hello_world/user_id/x

Note: This is not a question of RESTful API design, rather the naming convention guidelines to use for the eventual path components and/or query string parameters used.

Any guidelines would be appreciated.

score 165 · Accepted Answer · edited Jun 27 '17 at 10:35

165

I think you should avoid camel caps. The norm is to use lower case letters. I would also avoid underscores and use dashes instead

So your URL should look like this (ignoring the design issues as you requested :-))

api.service.com/hello-world/user-id/x

edited Jun 27 '17 at 10:35

Rishabh Agrawal

1,998
2
25
40

answered Apr 24 '09 at 13:15

LiorH

18,524
17
70
98

190

According to RFC2616 only the scheme and host portions of the URL are case-insensitive. The rest of the URL, i.e. the path and the query SHOULD be case sensitive. http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.2.3 – Darrel Miller Jun 05 '10 at 03:00
11

Daniel, you are right, thanks for pointing that out. However, de-facto we usually expect urls to ignore cases, especially the resource name part. It would make no sense for userid & UserId to behave differently (unless one of them returns 404) – LiorH Jun 05 '10 at 09:12
19

@LiorH: Why do you think it "makes no sense" to be case-sensitive? Plenty of other contexts are case sensitive to good effect. There are some web services (e.g. Amazon S3) that *do* enforce case sensitivity for URL endpoints, and I think it's quite appropriate. – Hank Dec 22 '11 at 18:44
2

The original intention of URLs was to map directly to a server's file system. There hasn't been a case insenstive file system that was net accessible in probably 40 plus yeers, if ever. (DOS was not used to run servers - Don't go there) – Dennis Jun 23 '12 at 14:06
6

@Dennis Windows server filesystems are case insensitive by default, unless I'm sorely mistaken http://technet.microsoft.com/en-us/library/cc725747.aspx – samspot Aug 14 '12 at 20:30
5

@samspot Good one! I thought that windows had gone straight to case sensitive file names when they created servers. WOW, they were still pushing THEIR way for as long as they could, i.e. "1 MicroSoft Way". ;-) – Dennis Oct 31 '12 at 12:50
NTFS has been case-sensitive for a very long time now, but mounting it case-insensitive is the default. In any case URLs definitely are case-sensitive and treating them otherwise is a serious misstep that will bite you some day. – Brad Jan 24 '15 at 19:56
What if the the user ID itself is case sensitive? e.g. api.service.com/hello-world/user-id/TheUsersCaseSensitiveId. Is it expected that any case-sensitive IDs should not be passed as URL parameters? – Ryan Burbidge Jan 27 '15 at 21:18
4

You say you *"would also avoid underscores"* but you do not give a reason for it? – Alvaro May 03 '16 at 11:02
@Dennis NTFS has always been a _case-remembering_ filesystem, not case-sensitive. Case-sensitivity for identifiers (in any platform) is silly: if you are distinguishing things exclusively by case, you've made a wrong turn. You'll still have to allow for the wrong turns of others (Postel's Law). Underscores are less convenient to type, and can be obscured by link underlines: https://api.example.com/hello_world/user_id/x – brianary Jun 27 '19 at 15:22

score 100 · Answer 2 · edited Dec 06 '15 at 19:47

100

The REST API for Dropbox, Twitter, Google Web Services and Facebook all uses underscores.

edited Dec 06 '15 at 19:47

Gajus

69,002
70
275
438

answered Jan 05 '12 at 06:26

jz1108

1,300
1
11
14

27

One of the side effects of that is that underscored 'words' are kept whole, together in google's search indexes. Hyhenated ones are broken into separate words. – Dennis Jun 23 '12 at 14:08
Example: https://dev.twitter.com/docs/api/1.1 – mike kozelsky Jan 22 '14 at 15:54
13

While the Google Maps API does uses underscores, the [Google Style Guide](http://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml?showone=Property_Name_Format#Property_Name_Format) requires Camel Case. The [Google+ API](https://developers.google.com/+/api/latest/activities/list) and [Custom Search API](https://developers.google.com/custom-search/json-api/v1/reference/cse/list), among others, use Camel Case. – Jade Jun 06 '14 at 16:23
2

Yet they still use '-' as the separator those urls :P https://developers.google.com/custom-search/json-api/v1/reference/cse/list https://developers.google.com/+/best-practices https://dev.twitter.com/overview/case-studies On the other hand they use camelCase in the query parameters. – Mattias Feb 23 '15 at 08:58
1

I think I would use underscores after all discussion here and [there](http://blog.octo.com/en/design-a-rest-api/#case) – Richard Fu Jul 12 '16 at 06:04
2

Nobody knows... – Piotr Kula May 24 '17 at 10:37
@Benjamin Aren't you confusing the URI with the content (json)? – user3285954 Jul 28 '17 at 12:13

score 85 · Answer 3 · edited Jun 03 '11 at 15:53

Look closely at URI's for ordinary web resources. Those are your template. Think of directory trees; use simple Linux-like file and directory names.

HelloWorld isn't a really good class of resources. It doesn't appear to be a "thing". It might be, but it isn't very noun-like. A greeting is a thing.

user-id might be a noun that you're fetching. It's doubtful, however, that the result of your request is only a user_id. It's much more likely that the result of the request is a User. Therefore, user is the noun you're fetching

www.example.com/greeting/user/x/

Makes sense to me. Focus on making your REST request a kind of noun phrase -- a path through a hierarchy (or taxonomy, or directory). Use the simplest nouns possible, avoiding noun phrases if possible.

Generally, compound noun phrases usually mean another step in your hierarchy. So you don't have /hello-world/user/ and /hello-universe/user/. You have /hello/world/user/ and hello/universe/user/. Or possibly /world/hello/user/ and /universe/hello/user/.

The point is to provide a navigation path among resources.

My question is more concerning the naming convention of the eventual pathnames and/or querystring parameters whatever they may be. I agree with you design recommendations, so thank you, but with this question I'm just asking about naming conventions. — jnorris, Apr 22 '09 at 18:02
Just to note, there's nothing stopping you from using REST for non-hierarchical resources. The actual URI naming conventions you use are immaterial, just use whatever you think looks nice and is easy for you to parse on the server. The client shouldn't know anything about generating your URIs since you need to send the URIs to resources via hypertext in your responses. — aehlke, Jul 21 '09 at 14:33

score 31 · Answer 4 · edited Jul 13 '15 at 10:22

31

'UserId' is wholly the wrong approach. The Verb (HTTP Methods) and Noun approach is what Roy Fielding meant for The REST architecture. The Nouns are either:

A Collection of things
A thing

One good naming convention is:

[POST or Create](To the *collection*)
sub.domain.tld/class_name.{media_type} 

[GET or Read](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[PUT or Update](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[DELETE](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[GET or Search](of a *collection*, FRIENDLY URL)
sub.domain.tld/class_name.{media_type}/{var}/{value}/{more-var-value-pairs}

[GET or Search](of a *collection*, Normal URL)
sub.domain.tld/class_name.{media_type}?var=value&more-var-value-pairs

Where {media_type} is one of: json, xml, rss, pdf, png, even html.

It is possible to distinguish the collection by adding an 's' at the end, like:

'users.json' *collection of things*
'user/id_value.json' *single thing*

But this means you have to keep track of where you have put the 's' and where you haven't. Plus half the planet (Asians for starters) speaks languages without explicit plurals so the URL is less friendly to them.

edited Jul 13 '15 at 10:22

mandark

762
5
21

answered Jun 23 '12 at 14:42

Dennis

747
7
15

What is meant with {var}? If I search for a user by name that would be for example .../user/username/tomsawyer ? – Dr. Hans-Peter Störr Oct 30 '12 at 10:47
1

If you had three variables (var)s named x, y, z, then you're URL would look like: http://sub.domain.tld/x/value_of_x/y/value_of_y/z/value_of_z – Dennis Oct 31 '12 at 12:41
@hstoerr Just to be sure I was clear, most script languages use some sort of 'curly bracket variable substitution'. So {var} signifies that some variable (it's name) resides there, and so the following {value} is where the value of the {var} before it. Example: sub.domain.tld/script/{var}/{value}.json [www.yelp.com/food_reviews/review_averages_higher_than/4.json ]would be trying to get the json results from yelp.com for food reveiws showing a value higher than 4. – Dennis Nov 13 '12 at 05:04
This is the best answer in my opinion and kudos for thinking internationally. – beiller Apr 20 '14 at 17:22

score 14 · Answer 5 · answered Jul 20 '09 at 22:31

14

No. REST has nothing to do with URI naming conventions. If you include these conventions as part of your API, out-of-band, instead of only via hypertext, then your API is not RESTful.

For more information, see http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

answered Jul 20 '09 at 22:31

aehlke

15,225
5
36
45

44

Give it a rest...it's still nice to have nice looking URLs. – Dave Mar 13 '12 at 20:33
1

Agree with @HDave, it's very much in the spirit of REST to have URLs which are easily comprehended. You're working with URLs, why wouldn't you want them to be as easily comprehended as the variable and parameter names in your code? – mahemoff Apr 20 '12 at 22:21
5

@mahemoff sorry, this is me being super pedantic. But what your URLs look like has nothing to do with REST. That does not mean that they're not a good thing to have, they're just orthogonal to what REST describes. It's misleading to say that REST is about structuring URLs this way, since it leads to people describing RPC APIs as REST just because they have readable / structured URLs. – aehlke Apr 23 '12 at 19:34
6

In summary, nice looking URLs are great and everyone should have them. It has nothing to do with REST though. – aehlke Apr 23 '12 at 19:35
1

@aehlke thanks for clearing this up. Rest isn't about URL structures. I don't understand why it's so hard for people to understand. – user1431072 Dec 17 '14 at 17:22
@user1431072 years of Rails etc. abusing the term "REST", unfortunately – aehlke Dec 17 '14 at 20:59

score 9 · Answer 6 · answered Aug 03 '09 at 18:14

9

Domain names are not case sensitive but the rest of the URI certainly can be. It's a big mistake to assume URIs are not case sensitive.

answered Aug 03 '09 at 18:14

score 5 · Answer 7 · edited Oct 18 '12 at 13:16

5

I have a list of guidelines at http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html which we have used in prod. Guidelines are always debatable... I think consistency is sometimes more important than getting things perfect (if there is such a thing).

edited Oct 18 '12 at 13:16

Andrew Barber

39,603
20
94
123

answered Oct 05 '12 at 09:27

Robert Morschel

341
3
11

score 4 · Answer 8 · edited Oct 07 '21 at 11:04

If you authenticate your clients with Oauth2 I think you will need underscore for at least two of your parameter names:

client_id
client_secret

I have used camelCase in my (not yet published) REST API. While writing the API documentation I have been thinking of changing everything to snake_case so I don't have to explain why the Oauth params are snake_case while other params are not.

See: https://www.rfc-editor.org/rfc/rfc6749

score 3 · Answer 9 · answered Apr 22 '09 at 16:55

3

I don't think the camel case is the issue in that example, but I imagine a more RESTful naming convention for the above example would be:

api.service.com/helloWorld/userId/x

rather then making userId a query parameter (which is perfectly legal) my example denotes that resource in, IMO, a more RESTful way.

answered Apr 22 '09 at 16:55

Gandalf

9,648
8
53
88

This is not a question of RESTful API design, rather the naming convention guidelines to use for the eventual path components and/or query string parameters used. In your example, should the path components be in camel caps as you have used, or underscores? – jnorris Apr 22 '09 at 17:01
Well since in REST your URLs are your interfaces, then it is kind of an API question. While I don't think there are any guidelines specific to your example, I would go with camel case personally. – Gandalf Apr 22 '09 at 17:44
You shouldn't use query parameters for resources that you want to be cached at any level of the HTTP stack. – aehlke Jul 21 '09 at 14:34
@aehlke The exact opposite holds true as well. If you DON'T want query parameters cached, use the GET style for the parameters, ~OR~ make DARN SURE to modify / insert anti caching headers for anything that you don't want cached. Also, thre is some header that is a hash of the object/page returend, use that to indicate changes of things you DO want cached, but updated when there's edits. – Dennis Oct 01 '13 at 14:57
@aehlke Found out about caching and am adding it. I remember a CodeCamp presentation where one of the speedups was doing all these headers, and then changing the file name and all references to it when it's contents changed in order to get borwsers and proxies to server a newer version after a long cache time had been set. Here is all the gory details: https://developers.google.com/speed/docs/best-practices/caching – Dennis Oct 01 '13 at 15:12

score 0 · Answer 10 · answered Apr 22 '09 at 17:01

I would say that it's preferable to use as few special characters as possible in REST URLs. One of the benefits of REST is that it makes the "interface" for a service easy to read. Camel case or Pascal case is probably good for the resource names (Users or users). I don't think there are really any hard standards around REST.

Also, I think Gandalf is right, it's usually cleaner in REST to not use query string parameters, but instead create paths that define which resources you want to deal with.

http://api.example.com/HelloWorld/Users/12345/Order/3/etc

Are there any naming convention guidelines for REST APIs?

10 Answers10

Linked