REST API Design – Using Verbs vs. Nouns in URIs

api-designrestweb-api

For people who will use an API, is it easier to see:

/createUser

/getUser/id

/editUser/id

The standard is to use nouns in URI eg:

/user/ POST (Create a user)
/user/ GET (Get list of users)

A developer is insisting on using verbs because it is easier for others. But I think there must be some real technical debts to pay later on, other than just a case of bad "grammar" and people laughing at us?

Best Answer

Standard URL mapping for REST has the resource mapped to the URL and what you do to it in the HTTP method.

It works well when interacting programmatically with your REST endpoint. It's also very discoverable and consistent: if you get a link to a resource, you know you can try other methods and - if supported - they'll behave in a standard CRUD pattern.

However, it can be somewhat inconvenient to debug from a browser, because they're not really design to do anything else than GET from the URL bar - so you need extra plugins (or use CURL/other tools).

Unfortunately, using the non standard mapping in the question (e.g. '/editUser/id') alone doesn't really solve that issue - you still need a body to go with the request, so I don't see how that makes it easier. Or lots of URL query parameters, but that breaks the symmetry between actions.

If by 'easier for others' your dev is meaning 'easier on people that try to access it from a basic browser for anything other than GET', then a way to do that would be to stick to the basic resource mapping but (optionally) stick the verb/method in a query parameter, e.g. /user/?action=DELETE. I'd still support the standard HTTP methods and make the above totally optional, not best practice, and for debugging/manual exploration only.