docs(rest-api): cleanup and document code examples 🌐

NeaByteLab · NeaByteLab · commit a3be8ea66055 · 2026-04-09T11:32:15.000+07:00
- Add JSDoc to HTTP semantics code examples

- Document payload validation functions

- Remove unnecessary comments from status-errors

- Update URI design examples with documentation
diff --git a/DEEP-NOTES/Rest-API/http-semantics.md b/DEEP-NOTES/Rest-API/http-semantics.md
@@ -67,13 +67,23 @@ Common API design decisions:
 **Good snippet (Express style):**
 
 ```ts
-// PUT endpoint - replace entire user resource
+/**
+ * Replace user resource completely.
+ * @description Performs full update of user data.
+ * @param req - Express request object
+ * @param res - Express response object
+ */
 app.put('/v1/users/:id', async (req, res) => {
   const user = await replaceUser(req.params.id, req.body)
   return res.status(200).json(user)
 })
 
-// PATCH endpoint - partial user update
+/**
+ * Partially update user resource.
+ * @description Applies partial modifications to user.
+ * @param req - Express request object
+ * @param res - Express response object
+ */
 app.patch('/v1/users/:id', async (req, res) => {
   const user = await updateUserPartial(req.params.id, req.body)
   return res.status(200).json(user)
@@ -83,9 +93,14 @@ app.patch('/v1/users/:id', async (req, res) => {
 **Bad snippet (semantic mismatch):**
 
 ```ts
-// Wrong: GET request that mutates server state
+/**
+ * Mutate server state incorrectly.
+ * @description Demonstrates anti-pattern of state mutation in GET.
+ * @param _req - Express request object unused
+ * @param res - Express response object
+ */
 app.get('/v1/logout', async (_req, res) => {
-  await revokeSession() // Mutation in GET violates HTTP semantics
+  await revokeSession()
   return res.status(200).json({ ok: true })
 })
 ```
diff --git a/DEEP-NOTES/Rest-API/payload-validation.md b/DEEP-NOTES/Rest-API/payload-validation.md
@@ -61,10 +61,14 @@ You need strong validation in:
 **Good snippet (schema first):**
 
 ```ts
-// Validate request body using schema before processing
+/**
+ * Validate request against schema.
+ * @description Parses and validates incoming request body.
+ * @param req - Express request with body
+ * @param res - Express response object
+ */
 const result = createPromptSchema.safeParse(req.body)
 if (!result.success) {
-  // Return structured validation errors with 422 status
   return res.status(422).json({
     code: 'validation_failed',
     details: result.error.issues
@@ -76,11 +80,9 @@ if (!result.success) {
 
 ```ts
 try {
-  // Direct database insert without validation - bad practice
   await db.prompts.insert(req.body)
   return res.status(201).json({ ok: true })
 } catch {
-  // Generic error hides real validation issues
   return res.status(500).json({ message: 'Something went wrong' })
 }
 ```
diff --git a/DEEP-NOTES/Rest-API/status-errors.md b/DEEP-NOTES/Rest-API/status-errors.md
@@ -72,7 +72,6 @@ Critical response mapping areas:
 
 ```ts
 if (!token) {
-  // Return 401 with structured error envelope
   return res.status(401).json({
     code: 'auth_missing',
     message: 'Authentication required',
@@ -85,7 +84,6 @@ if (!token) {
 
 ```ts
 if (!token) {
-  // Wrong: 200 status hides the actual error condition
   return res.status(200).json({
     error: true,
     message: 'Unauthorized'
@@ -109,7 +107,6 @@ if (!token) {
 - Include `requestId` for tracing support tickets
 
 ```json
-// Structured error response with all required fields
 {
   "code": "validation_failed",
   "message": "Payload validation failed",
diff --git a/DEEP-NOTES/Rest-API/uri-design.md b/DEEP-NOTES/Rest-API/uri-design.md
@@ -59,15 +59,17 @@ You apply URI design on:
 
 **Good snippet (resource-first):**
 
+Resource-first URI with query parameters:
+
 ```http
-// Resource-first URI with query parameters for filtering
 GET /v1/users/42/sessions?limit=20&offset=0
 ```
 
 **Bad snippet (action-first):**
 
+Action-first URI violates REST principles:
+
 ```http
-// Action-first URI violates REST principles
 POST /v1/getUserSessionListById
 ```
 
