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

User · Answer

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

User · Answer

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

User · Answer

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

User · Answer

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 amp 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

User · Answer

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

User · Answer

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   tools ietf org html rfc6749

User · Answer

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

User · Answer

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

User · Answer

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

User · Answer

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

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

Examples related to api

Examples related to rest

Examples related to naming-conventions