docs(rest-api): add descriptive comments to code examples ✏️

NeaByteLab · NeaByteLab · commit 9402a2d8d23a · 2026-03-28T14:40:32.000+07:00
- Add validation comments to payload validation examples
- Add semantic comments to HTTP method examples
- Add error envelope comments to status code examples
- Add URI design comments to resource-first examples
- Add RESTful endpoint comments to API fundamentals
diff --git a/DEEP-NOTES/Rest-API/api-fundamentals.md b/DEEP-NOTES/Rest-API/api-fundamentals.md
@@ -66,6 +66,7 @@ You are usually in REST territory when:
 **Good snippet (uniform contract):**
 
 ```http
+# RESTful endpoints using proper HTTP methods
 GET /v1/prompts
 POST /v1/prompts
 PATCH /v1/prompts/{id}
@@ -75,6 +76,7 @@ DELETE /v1/prompts/{id}
 **Bad snippet (action endpoints):**
 
 ```http
+# Action-based endpoints violate REST principles
 POST /v1/getPromptsList
 POST /v1/removePromptById
 POST /v1/updatePromptById
diff --git a/DEEP-NOTES/Rest-API/http-semantics.md b/DEEP-NOTES/Rest-API/http-semantics.md
@@ -67,11 +67,13 @@ Common API design decisions:
 **Good snippet (Express style):**
 
 ```ts
+// PUT endpoint - replace entire user resource
 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
 app.patch('/v1/users/:id', async (req, res) => {
   const user = await updateUserPartial(req.params.id, req.body)
   return res.status(200).json(user)
@@ -81,8 +83,9 @@ app.patch('/v1/users/:id', async (req, res) => {
 **Bad snippet (semantic mismatch):**
 
 ```ts
+// Wrong: GET request that mutates server state
 app.get('/v1/logout', async (_req, res) => {
-  await revokeSession()
+  await revokeSession() // Mutation in GET violates HTTP semantics
   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,8 +61,10 @@ You need strong validation in:
 **Good snippet (schema first):**
 
 ```ts
+// Validate request body using schema before processing
 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
@@ -74,9 +76,11 @@ 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,6 +72,7 @@ Critical response mapping areas:
 
 ```ts
 if (!token) {
+  // Return 401 with structured error envelope
   return res.status(401).json({
     code: 'auth_missing',
     message: 'Authentication required',
@@ -84,6 +85,7 @@ if (!token) {
 
 ```ts
 if (!token) {
+  // Wrong: 200 status hides the actual error condition
   return res.status(200).json({
     error: true,
     message: 'Unauthorized'
@@ -107,6 +109,7 @@ 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
@@ -60,12 +60,14 @@ You apply URI design on:
 **Good snippet (resource-first):**
 
 ```http
+// Resource-first URI with query parameters for filtering
 GET /v1/users/42/sessions?limit=20&offset=0
 ```
 
 **Bad snippet (action-first):**
 
 ```http
+// Action-first URI violates REST principles
 POST /v1/getUserSessionListById
 ```
 
