It's a pretty established convention that database table names, in SQL at least, should be singular. SELECT * FROM user;
See this question and discussion.
It's also a pretty established convention that RESTful API resource names should be plural. GET /users/123
and POST /users
See this one.
In the simplest database-backed API, the name of the resource in the URL would be the table, and the data elements in the URL and request/response bodies would map directly to the columns in the DB. Conceptually, I don't see a difference between operating on the data through this theoretical API versus operating on it directly through SQL. And because of that, the difference in naming conventions between user
and users
doesn't make sense to me.
How can the difference in pluralization be justified when, conceptually, the REST API and the SQL are doing the same thing?
Best Answer
The REST spec (whatever level you want to go with) wasn't designed as database access. It is trying to bring standardization to API access. The SQL conventions mentioned (whether you want to use them or not) were not designed with API access in mind. They are for writing SQL queries.
So the issue to unpack here is the conceptual understanding that an API maps directly to the database. We can find this described as an anti-pattern at least as far back to 2009.
The principal reason this is bad? The code describing "how does this operation affect my data?" becomes client code.
This has some pretty terrible effects on the API. (not an exhaustive list)
It makes integrating with the API difficult
I imagine the steps to create a new user documented as something like this:
POST /users { .. }
POST /usersettings { .. }
with some default valuesPOST /confirmemails { .. }
But how do you handle a failure of step #2? How many times is this same handling logic copy-pasta'd to other clients of your API?
Securing the API becomes a black hole of despair
Let's say you need to merge two user accounts.
GET /users/1
PUT /users/2 { .. }
DELETE /users/1
How are you going to setup a user permission to allow the merge feature while not allowing user deletion? Is deleting a user even fairly represented by
DELETE /users/1
when/usersettings
also exists?Maintenance becomes harder
... because your clients depend on your database structure.
Based on my experience with this scenario:
So if you are using an API as just an interface straight into a database, pluralization is the least of your worries. For other than a throw-away experiment, I would suggest spending some time determining the higher-level operations the API should represent. And when you look at it that way, there's no conflict between pluralized API entity names and singular SQL entity names. They are there for different reasons.