Group API endpoints into topic folders

What you'll see

An application starts with a handful of endpoints and the developer drops them all directly into #/API/: getOrders.js, createOrder.js, getUser.js, updateUser.js, listProducts.js, and so on. As the app grows, this single folder accumulates dozens of files. Finding the right endpoint means scrolling a long, flat list; names start colliding (getList.js — list of what?); and the prefixing convention (order_, user_) becomes a manual workaround for the missing structure.

What's actually happening

Every .js file placed in #/API/ becomes a server-side REST endpoint, and the file's path under #/API/ maps directly to its URL. A file at #/API/hello.js is served at /API/hello. Crucially, this mapping is recursive: subfolders are part of the URL too. A file at #/API/orders/create.js is served at /API/orders/create, and #/API/users/profile.js at /API/users/profile.

This means folders under #/API/ are not just an organisational nicety for the file tree — they are a first-class part of your API's URL design. Docly does not require any routing configuration or manifest to make this work; creating the folder and dropping the file in is the entire setup.

A flat #/API/ with everything in the root loses this for free. Endpoints from unrelated features sit side by side, the file list grows without grouping, and developers resort to encoding the topic into the filename (order_create.js, user_profile.js) to claw back some grouping. That produces ugly URLs like /API/order_create and re-implements, by hand and inconsistently, exactly what folders give you automatically.

What to do

Group related endpoints into topic folders under #/API/, one folder per resource or feature area. Let the folder name carry the topic and the file name carry the action. The result is readable, RESTful URLs and a file tree that scales.

Do — topic folders, action filenames:

#/API/orders/list.js      ->  /API/orders/list
#/API/orders/create.js    ->  /API/orders/create
#/API/orders/cancel.js    ->  /API/orders/cancel
#/API/users/profile.js    ->  /API/users/profile
#/API/users/update.js     ->  /API/users/update
#/API/billing/invoice.js  ->  /API/billing/invoice

Don't — everything flat in the root with prefixes:

#/API/orderList.js        ->  /API/orderList
#/API/orderCreate.js      ->  /API/orderCreate
#/API/order_cancel.js     ->  /API/order_cancel
#/API/getUserProfile.js   ->  /API/getUserProfile
#/API/updateUser.js       ->  /API/updateUser
#/API/invoice.js          ->  /API/invoice   // invoice for what?

The endpoint code itself does not change — the same exported function works regardless of which folder it lives in:

// #/API/orders/create.js
export default (form) => {
    if (!form.product) return { error: "Missing product" };
    // ... create the order
    return { ok: true };
}

From the frontend, call the grouped endpoint exactly as you would a flat one — just include the folder in the path (and prefer ~/ so it survives publishing under a subfolder):

fetch('~/API/orders/create', {
    method: 'POST',
    body: new URLSearchParams({ product: 'SKU-42' })
});

A practical rule of thumb: once you have more than a few endpoints, or as soon as two endpoints belong to the same resource, create a folder. Keep #/API/'s root reserved for genuinely cross-cutting, app-wide endpoints (for example a single #/API/health.js), and put everything feature-specific in its own topic folder.