Software Engineering Stack Exchange is a question and answer site for professionals, academics, and students working within the systems development life cycle. It only takes a minute to sign up.
Sign up to join this community
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?
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.
What are the consequences of using verbs instead of nouns in REST API URI?
None. At. All.
/7dc54421-5573-4b21-ad5e-6d6aa458ea79 is a perfectly fine URI
http://a.co/3sRiNxj <- is that a noun? a verb? but I bet your browser can figure out how to GET it anyway.
http://www.dictionary.com/browse/patch <-- oh no! how can we GET a page from an online dictionary that defines a verb? Are we supposed to GET or PATCH this resource?
...or maybe it just works.
URI are identifiers; the encoding of information into that identifier is done at the server's discretion and for its own use.
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?
Really, identifier spelling is matter of convention, subject to concerns relating to the reference resolution. You treat it like a variable naming convention; conforming to local idiom is more important than general concerns.
Part of the point of hypermedia in general is that the identifiers are just identifiers; we don't try to use the spelling of them to communicate information.
In other words, the spelling of the URI isn't supposed to tell you what it is.
For example
<img src="http://example.org/mdn-logo-sm.txt" alt="MDN">
Should the browser freak out because the URI ends with ".txt"? Of course not; it's just an identifier
GET /mdn-logo-sm.txt HTTP/1.1
...
200 OK
Content-Type: image/gif
The browser knows how to process the representation it receives because the response metadata identifies the media-type of the payload. The spelling of the identifier has nothing to do with it.
Using verbs in your URL may create confusion in human users, unless those URLs present forms for performing the action suggested. That's the only problem.
The object identified by the URL will always be an information resource (a noun), which may in turn correspond to a real-world object, process, concept etc.
As mentioned, the only unambiguous use of a verb is as part of a compound noun, such as /users/adam/edit-form which would present a form (in HTML or XML or whatever) for editing the user "adam".
For people who will use an API, is it easier to see:
This sounds like an assumption. Who are these "people" exactly? And how do you know what they will find easy? Were "the people" asked this question or was the assumption made without asking?
The standard is to use nouns in URI eg: /user/ POST (Create a user) /user/ GET (Get list of users)
You have a mistake here, should be POST /users not POST /user
What are the consequences
Suggested approach is not idiomatic to web apis, it looks more like a C library than a web api. You can think of it, as of a person who is speaking a foreign language that (s)he didn't master very well yet and is borrowing grammar from his native language to express ideas. You can understand but it doesn't sound right and there probably will be expression issues if you need to discuss more complicated topics.
It's possible to have basic conversations without mastering language in details and is also possible to build simple functional web apis without mastering http design principles. Consequences will start showing up if you want to scale the api and will want to make use of existing http infrastructure which usually come in form of gateways, proxies, and client-side libraries. Things will be possible just everything will be harder.
In the end consequence is that every subsequent player that will need to deal with this api will need to deal with it sounding somewhat foreign. And there are many different players: - end user (potentially your frontend developer, or 3rd party developers if you are building SAS) - load balancers - caching proxies - api gateways
One affected area will be caching. HTTP is designed in a way that allows very effective caching layer to sit between client and your application without having any knowledge of your application logic. Cache layer will use resource url as a key:
/users/<id>
Caching layer could be configured to invalidate the cache if write requests (POST/PATCH/PUT) are detected to that path.
Another affected are will be access control. Just like with caching if you will ever want to make use of existing web infrastructure to manage access control to your API (as opposed to implementing it inside your application's code) then following http best practices will make this possible.
You could configure a gateway, to allow unauthorized read requests to /users/<x>, but block all unauthorized write requests. A token containing scope users/1 and permission level owner could instruct a middle-layer gateway to allow all write requests to /users/1. An administrator's token that has scope users and permission level owner could allow write requests to any user.
Maybe you want to make use of off-the-shelf application that handles certain feature for example commenting instead of developing your own. You'll might then need multiple applications running under a common url umbrella. This can be handled with gateway and routing. If off-the-shelf application that handles comments follows good practices good chance is that you only will need to add single route /comments and point it to that application.
/comments/<X> - app1
/users/<X> -- app2
if you used api suggested by your developer then chances are routing might need to be a lot more complex at some point.
user,getUserorfoobarbaz. That being said, "because it is easier for others" doesn't seem to be a strong enough reason not to respect the convention of using nouns here (and following conventions is usually what is easier for others). – Vincent Savard Jan 5 '18 at 16:24getis implied in the GET verb; putting it in the URL is redundant. REST URLs are about resources (i.e. NOUNS), not actions. REST actions remain squarely within the province of the GET, PATCH, PUT and POST verbs. – Robert Harvey Jan 5 '18 at 17:19