3

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?

3
  • 1
    What kind of technical debt are you expecting? All other things equal, it's just a word, there's no technical impact whether you call it user, getUser or foobarbaz. 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:24
  • 6
    This just sounds like inexperience on the part of your developer to me. The word get is 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
  • 2
    Of course, if you intend to depart from strict REST (a common occurrence in many non-trivial API's unless you're strictly performing CRUD operations) and use POST for i.e. RPC calls, then feel free to name those things anything you want. – Robert Harvey Jan 5 '18 at 17:20
9

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.

2
  • 6
    There are so many quality REST clients out there today that "its hard/impossible from within a browser" is really just a lazy excuse. – marstato Jan 5 '18 at 16:41
  • 1
    I don't disagree - but you might be a in a situation where such a client is not readily available (not your machine, on a mobile/ipad, from a customer's infrastructure, etc.) Plus being lazy is a virtue in a programmer (Larry Wall). – ptyx Jan 5 '18 at 20:56
5

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.

2
  • 5
    Yes, browsers and web servers don't care what you do. If humans never had to read and understand URIs your point might be valid. – Karl Bielefeldt Jan 5 '18 at 18:26
  • 1
    If all API REST were HATEOAS, this would be the only valid answer. – Laiv Jan 8 '18 at 19:06
0

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".

0

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

Caching

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.

ACL

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.

Routing

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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