Are there any naming convention guidelines for REST APIs? [closed]

Answer 1

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

Answer 2

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

1. A Collection of things
2. 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.

Answer 3

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

Answer 4

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.

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

Answer 6

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.