Rules Hub
Coding Rules Library
Design clean, semantic API routes
Avoid file extensions in URL paths and organize routes by access scope (public vs. private) to improve maintainability and security.
Bad example
| 1 | // src/app/route/api/common/index.ts |
| 2 | export const commonRouter = Router(); |
| 3 |
|
| 4 | // BAD: Mixed scope and legacy .json extension |
| 5 | commonRouter.get('/articles/by-tag.json', articlesByTag); |
Explanation (EN)
The route uses a file extension (`.json`), which is a legacy practice, and is placed in a generic `commonRouter`. This mixes public and private logic and creates brittle, static-file-like URLs.
Objašnjenje (HR)
Ruta koristi ekstenziju datoteke (`.json`), što je zastarjela praksa, i smještena je u generički `commonRouter`. To miješa javnu i privatnu logiku te stvara krhke URL-ove koji nalikuju statičkim datotekama.
Good example
| 1 | // src/app/route/api/private/index.ts |
| 2 | export const privateRouter = Router(); |
| 3 |
|
| 4 | // GOOD: Clearly scoped under private, clean URL without extension |
| 5 | privateRouter.get('/articles/by-tag', articlesByTag); |
Explanation (EN)
The route is moved to a dedicated `privateRouter`, clarifying its access scope. The `.json` extension is removed in favor of standard HTTP content negotiation or default JSON behavior.
Objašnjenje (HR)
Ruta je premještena u namjenski `privateRouter`, čime se jasno definira njezin opseg pristupa. Ekstenzija `.json` je uklonjena u korist standardnog HTTP pregovaranja o sadržaju ili zadanog JSON ponašanja.
Notes (EN)
Only use file extensions in URLs if the endpoint explicitly supports multiple return formats (e.g., .xml vs .json) dynamically. Otherwise, rely on 'Accept' headers.
Bilješke (HR)
Koristite ekstenzije datoteka u URL-ovima samo ako krajnja točka eksplicitno podržava više formata (npr. .xml vs .json) dinamički. U suprotnom, oslonite se na 'Accept' zaglavlja.