title: REST API Resource Naming Conventions - User or Users (pluralisation)
body: <h2>Long Version</h2>
  
  <p>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.</p>
  
  <p>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:</p>
  
  <pre><code>GET /notifications
  POST /posts
  </code></pre>
  
  <p>However, there are cases where pluralising just doesn't seem correct. Consider the following example where <code>user</code> essentially represents the logged in user, not the entire <code>users</code> resource:</p>
  
  <p><strong>Endpoints only relevant to the authenticated user</strong></p>
  
  <pre><code>// 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
  </code></pre>
  
  <p><strong>Endpoints that access the entire users resource</strong></p>
  
  <pre><code>GET /user
  GET /user/{id|self}
  </code></pre>
  
  <p>In the above example, to me, it <em>feels</em> like the singular <code>user</code> resource name is more suited given on the majority of the endpoints, <code>user</code> refers to the authenticated <code>user</code>, not the entire database of <code>users</code>. But, on the other hand, having <code>GET /user</code> return all users just seems plain wrong...</p>
  
  <p>As a result, I am now torn between <code>user</code> and <code>users</code> - both have strong arguments either way as I see it but would very much welcome another person's opinion on the matter...</p>
  
  <hr>
  
  <h2>Short Version</h2>
  
  <p>TLDR - To put it simply, consider the following two endpoints:</p>
  
  <pre><code>// Get all users
  GET /users
  
  // Update the authenticated user's device token
  PUT /user/device
  </code></pre>
  
  <p>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 <code>user</code> and <code>users</code>, it has to be one or the other in my opinion.</p>
  
  <p>The dilemma; Why would I use <code>user</code> when the resource refers to the entire users database? Why would I use <code>users</code> when the resource only refers to the authenticated user?</p>
  
  <p>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?</p>
  
  <hr>
  
  <h2>Update</h2>
  
  <p>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 <code>auth</code> resource name.</p>
  
  <p>Consider this:</p>
  
  <pre><code>// 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}
  </code></pre>