Are there any naming convention guidelines for REST APIs?

Viewed 195144

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.

10 Answers

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

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.

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.

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.

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

Related