API Route Structure

Purpose

⚠IMPORTANT⚠This skill enforces strictly deterministic RESTful topologies. It prohibits the algorithmic generation of non-uniform endpoint vectors that inject action verbs into resource locators.

When to Use This Skill

⚠NOTE⚠Use this skill whenever you are defining how the frontend communicates with the backend, or when exposing a public API.

What This Skill Prevents

This skill prevents:

• RPC Mutation: Injecting execution instructions into the URI path vector (e.g., POST /api/getUsers).
• Schema Variance: Emitting inconsistent JSON geometries based on operational status (e.g., array on 200, string on 400).
• HTTP Verb Obfuscation: Executing read-only queries via POST payloads.
• Memory Exhaustion: Executing unbounded SQL SELECT * operations returning raw $O(N)$ arrays to the client.

Core Principle

Endpoint topology MUST adhere to uniform interface constraints. State transfer must rely strictly on standardized HTTP verb mutations applied to pluralized resource locators. All payload emissions must follow a strict, deterministic JSON envelope.

Research-Backed Rules

• Resource Noun Assertion: Endpoints MUST evaluate as pure resource locators (nouns). Verbs are strictly prohibited (/api/users, not /api/getUsers).
• Pluralization Vector: Collections MUST assert plural noun schemas (/api/users over /api/user).
• Idempotency Invariants: PUT and DELETE commands must assert idempotency (repeated $N$ execution yields the identical state as $N=1$). PATCH is mandated for partial matrix mutations.
• Pagination Constraint (Cursor vs. Offset): Unbounded array emission is prohibited. Default to Cursor-based indexing for $O(1)$ stability on high-frequency insertion datasets. Offset indexing is permitted exclusively for static, low-mutation arrays where random access is a strict $O(1)$ requirement.

Stack-Aware Guidance

Express / Node Guidance

Bind related topologies into isolated Router instances.

router.get('/users', getUsers);       // List
router.post('/users', createUser);    // Create
router.get('/users/:id', getUser);    // Read
router.patch('/users/:id', updateUser); // Update
router.delete('/users/:id', deleteUser); // Delete

Next.js Route Handlers Guidance

Next.js App Router enforces file-system directory topology for endpoint resolution.

• app/api/users/route.ts (Resolves GET collection, POST creation)
• app/api/users/[id]/route.ts (Resolves GET singular, PATCH mutation, DELETE removal).

Implementation Guidance

1. Resource Identifier mapping: Extract the noun base constraint (articles, orders).
2. Matrix the Methods: Apply exact CRUD operations to standard HTTP protocols mapping the chosen identifier.
3. Normalize Emission Envelope: Ensure output payloads conform to a strict schema wrapper, e.g., { data: [...], meta: { pagination: ... } }.
4. Status Code Mapping: Return deterministic HTTP headers: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found.

Mathematical / Measurable Rules

• Pagination Constraint: Assert upper bound vector memory limits ($N \le 100$) for all collections to prevent database thread starvation.

Quality Gates

Maintainability Gate

• Confirmed resource URLs adhere to strictly pluralized noun topologies without verbs.
• Validated standard HTTP method mapping constraints.
• Asserted bounded pagination algorithms on collection reads.

Anti-Patterns to Avoid

• Status Code Hallucination: Returning a 200 OK header carrying an error body {"error": "User not found"}. Strict mapping to 404 is required.
• Graph Depth Exhaustion: Emitting nested parameter paths (/api/users/:userId/posts/:postId/comments/:commentId). Limit parameter depth to $d \le 1$; query sub-resources directly if unique identifiers exist (/api/comments/:commentId).

Agent Behavior Instructions

1. Map HTTP endpoint topology matrix prior to generation.
2. Enforce strict REST schema constraints unless executing specific GraphQL/RPC procedures.
3. Wrap all state outputs in deterministic, typed JSON envelopes.

Final Review Checklist

• Action verbs stripped from URIs.
• HTTP standards enforced.
• Pagination limits active.
• Status codes resolve deterministically.
• Fully agent-optimized deterministic rules.