As REST is not a single written standard there are some things you have to argue with each developer. And of course, you can always find arguments to support any side on the internet.

So this is my list of things you should be doing wit REST that are more fuzzy (not the obvious). To be built up with references.

Plural or Singular

SINGULAR !

We have long established that our database table names are singular. It is funny that we go around and start the discussion again for each new technology :-)

  • My biggest issue with plural is English - Class is not Classs, it is Classes. Person is People, Mouse is Mice.
  • Existing system using Singular: one implementation I see the DB tables are singular, the object names in SOAP and API are Singular, but the REST interface is Plural, and mappings were left to the imagination of the developer. Just noticed that even the data returned as collections is singular (e.g. "Entry":[], not "Entries":[]).
  • Would you like the url http://somewhere/users/scottp, or /user/scottp
  • Would you like to have your unix directory as '/homes/scottp' or just '/home/scottp'

It seems that the argument for using singular was won long ago - lets not redebate an old topic.

Best Practice

Read this: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

I agree with all of those design ideas, with one small exception.

Singular - always singular, not plural. If you used Plural, you would have to write: Emails; Faces; Cities; ... (TODO).

Important thing is: Keep it the same. So still better to be always plural than changing. But I prefer singular. It is an old rule being done by Database designers for table names.

  • Plural - People and Emails table, join table would have IDs "people_id" and "emails_id" - very odd looking since it is a person.
  • Singular - Persona and Email table, join table would have IDs "person_id" and "email_id" - very readable.

My take away on this is - don't reinvent - DB designers have been using Singular for decades, for a good reason.