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.

Answer 1

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.

Answer 2

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

Answer 3

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 you can use, 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/word/user/ and hello/universe/user/. Or possibly /world/hello/user/ and /universe/hello/user/.

The point is to provide a navigation path among resources.

Answer 4

I think you should avoid camel caps, as urls are not case sensitive. 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

Answer 5

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

Answer 6

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.