REST API Resource Naming Conventions - User or Users (pluralisation)

Question

Long Version

For some, myself included, one of the most painful and headache causing parts of building a REST API is determining the name for each resource and the accompanying endpoints.

Whilst it is, of course, down to personal preference; there are certain things that are encouraged by the community. For example, most people, including me, will pluralise their resource names:

GET /notifications
POST /posts

However, there are cases where pluralising just doesn't seem correct. Consider the following example where user essentially represents the logged in user, not the entire users resource:

Endpoints only relevant to the authenticated user

// Phone Verification
POST /user/phone/request
POST /user/phone/resend
POST /user/phone/verify

// User creation based on authenticated and verified phone
POST /user

// Update authenticated user's profile
PUT /user

// Delete the authenticated user
DELETE /user

// Add/remove the authenticated user's profile image
POST /user/image
DELETE /user/image

// Update the authenticated user's device token
PUT /device/token

Endpoints that access the entire users resource

GET /user
GET /user/{id|self}

In the above example, to me, it feels like the singular user resource name is more suited given on the majority of the endpoints, user refers to the authenticated user, not the entire database of users. But, on the other hand, having GET /user return all users just seems plain wrong...

As a result, I am now torn between user and users - both have strong arguments either way as I see it but would very much welcome another person's opinion on the matter...

---

Short Version

TLDR - To put it simply, consider the following two endpoints:

// Get all users
GET /users

// Update the authenticated user's device token
PUT /user/device

Both of the above seem correct in my eyes. The problem with the above is that there is no way I am going to have both user and users, it has to be one or the other in my opinion.

The dilemma; Why would I use user when the resource refers to the entire users database? Why would I use users when the resource only refers to the authenticated user?

I cannot get my head around this one... Anyone got any thoughts on this? Or, even better, an alternative solution to my proposed endpoint structure?

---

Update

After some deep thinking, I have come up with an alternative solution to this but I am still not 100% sure on it as I am not overly keen on using the auth resource name.

Consider this:

// auth = authenticated user
// users = users collection

POST /auth/request
POST /auth/resend
POST /auth/verify

POST /auth
PUT /auth
DELETE /auth

POST /auth/image
DELETE /auth/image

PUT /auth/device/token

GET /users
GET /users/{id}

Answer 1

There are obviously different opinions on this matter, the answer below contains my personal views. The bottom line is that it's all quite subjective and depends on the way one looks at a certain (type of) resource.

Why would I use user when the resource refers to the entire users database?

In my opinion, you should never use singular for an endpoint that contains multiple resources.
Some people, however, argue that we should stick to singulars for all resources, mostly for the sake of simplicity and uniformity.

Why would I use users when the resource only refers to the authenticated user?

You will find quite some different opinions on this, but the consensus and most widely adopted is generally to stick with plurals, except for resources that can only contain a single item (for example, a user profile only containing only one avatar).
Also, since using a singular form for the users resource wouldn't make sense following the above logic, we don't want to mix singular and plural names.

// Update the authenticated user's device token
PUT /user/device

You can interpret 'updating the authenticated user's device token' as follows:
Add a device token to a user entity of the users resource collection.

Answer 2

If your API supports view devices' data of other users, the API can be like /users/$user_id/devices

whereas, when you always have to get the current logged-in user's devices information, the API can simply be /devices (as current user is implied).

i.e IMO, wherever you have only 1 parent resource accessible (say in this case current user is always singular), you can skip that resource in the API URL.