I was in a job interview demo-ing a RESTful API in Flask when an argument broke about the API. The interviewer argued that the URL for adding a new user (/users/new) is not proper REST.

My API endpoint looked pretty much like below:

GET /users       # get all users
GET /users/1     # get user 1
DELETE /users/1  # delete user 1
POST /users/new  # add new user

His thesis

  • It should be /users for consistency with the rest of API.
  • It should be /users because the operation is in the HTTP method itself (POST) so new is not consistent.

My thesis

  • URL can be anything as long as it points to a resource and that it's more of a stylistic thing.
  • RubyOnRais uses this convention so it can't be totally wrong.

In retrospection I get the validity of his argument. However it contradicts what one of the most popular web frameworks is doing. Is there a consensus on what a URL can look like and what not in a RESTful API? In this case is an entire web framework wrong?

An other way to look at this is that /users is a "multiple of users" while /users/x correspondes to "single user", in which case the convention I used, makes sense.

  • 2
    The verb is king. A POST to /users is an "add" (new) operation. So far everything I've used and programmed myself works like that. Mar 8, 2018 at 12:53
  • 6
    On Rails, /users/new is a GET which points to new user form page and that form is sent to POST /users
    – MBraiN
    Mar 8, 2018 at 13:05
  • 2
    @MBraiN Yeah, in rails the /new URL is used purely to serve the page containing the HTML form that the user can fill in to create a new user. If you are creating a pure API then this is not used, it's only used when you also want a web interface. Mar 8, 2018 at 16:43
  • RubyOnRais uses this convention so it can't be totally wrong. probably RoR devs doesn't care about REST conventions. Or they did their own interpretation. But it doesn't mean they are right just because they have a framework. Nobody code for the state of the art.
    – Laiv
    Mar 8, 2018 at 20:42

1 Answer 1


REST doesn't care what spelling you use for your URI

Example: when you submitted this question to stack exchange, adding a "new" question to the /questions collection, did you need to look at the URI to do it? No, of course not. All you needed to do was submit the form.

REST does care when the same spelling is used. For example, RFC 7234 describes cache invalidation

A cache MUST invalidate the effective Request URI (Section 5.5 of [RFC7230]) as well as the URI(s) in the Location and Content-Location response header fields (if present) when a non-error status code is received in response to an unsafe request method.

So you may want to give the collection an identifier (ex: /users) and then use the same identifier for both reading the collection and modifying it, giving the intermediary components the information they need so that they don't respond to requests with copies of stale representations.

(Note: there's no magic - your POST is going to invalidate the representation in your local cache, but my local cache is going to be unchanged; I'll be working from stale data until my own cache gets invalidated).

In other words, you send your "create a user message" to the same resource as the "get all users" message for the same reason that you send the "delete a specific user" message to the same URI as the "get a specific user" message: so that the intermediary components can contribute usefully.


GET  /49647c1e-1441-46ea-80a3-676d3c02884b   # get all users
POST /49647c1e-1441-46ea-80a3-676d3c02884b   # add a new user

GET    /2a834d1a-a8d3-4dac-86e7-ca29d15a1eb2   # get user 1
DELETE /2a834d1a-a8d3-4dac-86e7-ca29d15a1eb2   # delete user 1

and you can use any spelling you like for those URI.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.