CODEWITHSUNDEEP
restresourcesnaming-conventionsuri
MarekLi
MarekLi

Reputation: 951

Mixing REST API plural and singular for different resources?

Plural form for REST api is more natural and more used e.g. /api/users or api/users/123.

But for some resources is not natural e.g.:

this resources never will be used for more that one object/model in my app.

On the other hand I read that mixing plural and singular form in resources names is not good practice (http://pages.apigee.com/web-api-design-ebook.html).

So I consider what to do:

  1. use singular for all
  2. use plural for all (with some stupid forms like /api/logins)
  3. to be inconsistent and use plural for almost all resources expect some special resources like /api/login or /api/profile which always used with one object/model.

What is the better approach?

Upvotes: 11

Views: 10392

Answers (4)

raspacorp
raspacorp

Reputation: 5307

What I've seen in some projects I've been working on these years is that singular looks more friendly for the most of common operations, you can have for example the following endpoints for the user resource:

GET /user  --> retrieves all users
GET /user/{id} --> retrieves a user with the given id
POST /user --> inserts a new user (the user object will come in the request body)
PUT /user/{id} --> updates a user with the given id (the user object will come in the request body)
DELETE /user/{id} --> deletes the user with the given id

Those are common operations, when you have bulk insert/update/delete operations then it should be better to use plurals

POST /users  (the user objects will come in the request body)
PUT /users/{listOfIds}  (the user objects will come in the request body)
DELETE /users/{listOfIds}

GET /user and GET /users would be synonyms, these two would accept query parameters to refine the results, for e.g.

GET /users?status=active

Upvotes: 3

jbuhacoff
jbuhacoff

Reputation: 1338

I'm not saying I prefer plurals, but if you are going with plurals you could reconcile your special singulars this way:

GET /api/forms/login is the HTML login form. Using this perspective, login is an ID of just one form in a collection of forms.

POST /api/forms/login is where the login form is submitted.

GET /api/users/{id}/profile retrieves the profile of the indicated user. This works for a lot of cases but does not work for anonymity sites where the identity of the user should remain hidden even while looking at their profile, which might leave out their user ID and real name.

GET /api/profiles/{id} decouples the profile entity from the user ID and would work for an anonymity site.

Alternatively, you could write GET /api/users/current/profile or GET /api/sessions/current/profile which omits a specific ID like in your post since the server will reply with the content relevant to the current user.

Upvotes: 6

Juned Ahsan
Juned Ahsan

Reputation: 68715

REST(Representational state transfer) is basically for a single entity and to do CRUD on it. So using singular make more sense to me. But in case when you need to get the list then plural make sense. For example:

You want to get a user then have /api/user/{id}

But if you want to get the list of users then have /api/users

Upvotes: 2

MarioDS
MarioDS

Reputation: 13063

There are no strict guidelines for defining a RESTful API, but what I read the most is that common sense should have the upper hand.

Therefore, option 3:

to be inconsistent and use plural for almost all resources expect some special resources like /api/login or /api/profile which always used with one object/model.

is the most logical. You should always be able to guess the URL when you think "I need resource X, how would this URL look like"?

Upvotes: 8

Related Questions