Should RESTful API URL be clean (/api/:param)?

patarapolw profile image Pacharapol Withayasakpunt ・1 min read

Clean URL is https://en.wikipedia.org/wiki/Clean_URL

A common pattern is

GET /articles
POST /articles
PUT /articles/:id
DELETE /articles/:id

Completely understandable, if you are doing it for SEO, but do RESTful API even need that? There might even be a security risk.

Some tutorials seem to explicitly prefer this, but why?

Actually, if querystring is used instead, it might be easier for axios + TypeScript (or any URL builders).


markdown guide

I think we should separate the concept of clean URLs from that of a progressive numeric IDs. The security risk is related to enumeration of numeric IDs tied to internal DB's primary keys.

But :id can be anything. A progressive number, a UUID, a ksuid or a slug or anything else that uniquely identifies a resource.

Security wise having the progressive numeric ID in the URL or in the query string doesn't change anything.


I do realize that being inside body might make no difference as well?

Unless it is inside HTTP-only cookies.


I do realize that being inside body might make no difference as well?

It does, GET operations, though technically can have a body, are going to be identified only by the URL. Most HTTP servers completely ignore the request body in a GET request.

Roy Fielding's comment about including a body with a GET request.

Yes. In other words, any HTTP request message is allowed to contain a message body, and thus must parse messages with that in mind. Server semantics for GET, however, are restricted such that a body, if any, has…

Unless it is inside HTTP-only cookies.

what do you mean?

Unless it is inside HTTP-only cookies.

Now, I might be wrong, but both Request body and HTTP-only cookies, can be tracked by Network Tab in Chrome Dev Tools, in user's PC.

The only time it will be a threat, is whether it can be tracked via remote computer... HTTP-only cookies should not be able to be traced by JavaScript tricks -- not sure about Request Body, but every parts of URL (segments, query) definitely can be recorded..

HTTP only cookies can't be read by JavaScript yes, but if someone has physical access to your computer they might be the least of your worries :D

The content of the back and forth in the HTTP requests is going to be encrypted by the transport protocol if you use TLS but your "network tab" is obviously going to be able to see the content of the request/response, the goal is here to encrypt it when it's traveling through the wire. If the browser weren't able to decrypt the transmission you wouldn't even see this comment I'm writing.

Hope this helps!


I'd say it's a bit of a reach to call it a security risk, especially in your example of articles. Users are a bit more sensitive, but as the Quora answers indicate: It really depends on the use case. Frontend routing libraries often invite or recommend similar patterns. It's not just about SEO, but for simplicity of structure. A well-architected REST API has an endpoint structure that is easy to reason about, just like a good frontend page/route structure.

Security certainly shouldn't be taken lightly, but it's important to remember that the "A" in the "CIA" of security is "Availability." That applies to DX as well as UX, and you shouldn't be so paranoid about security that you make life impossible for users or devs (and making it harder on the latter will inevitably make it harder on the former).


REST stands for REsource State Transfer (en.wikipedia.org/wiki/Representati...) being "resource" the keyword here. URI's uses the resource name (article in you example) to identify the resource being "mutated".

That´s why RESTful URLs have this format. That being said, resource names are not a security risk by themselves. Identifiers, OTOH, are quite indicative so, for that, you can rely on a numerous strategies to hide (or minimize) the exposure of you resources (hashes, UUIDs, etc.).

Again, RESTful approach uses HTTP verbs as the mechanism to achieve the "state transfer". It's argumentative that this would be a security risk since the web is based on HTTP and its verbs. And, by itself, REST is just one way of doing things.

Querystring is easier but it poses a much higher security risks since all data traffic is exposed on the URL and not even encrypted by HTTPS.

And, finally, REST is not about SEO. Usually REST URLs are not public facing websites. They should only be used to access some sort of REST APIs and be protected by tokens and other security mechanisms (HTTPS, API keys, Oauth2) meaning, they would and should not be indexed by search engines.

Hope it helps understand the meaning of things.