update services doc to libs

Docs/Libs/FastAPI/08.Status-Codes.md

@@ -0,0 +1,192 @@
+# FastAPI – HTTP Status Codes and Error Handling
+
+This document demonstrates how to use **HTTP status codes** in FastAPI to accurately represent the result of an API operation.
+Correct status codes improve API reliability, observability, and client-side behavior.
+
+---
+
+## Example Application
+
+Create or update `main.py` with the following content:
+
+```python
+from fastapi import FastAPI, status, HTTPException
+
+app = FastAPI()
+
+users = [
+    {"name": "abbas", "age": 20},
+    {"name": "mmd", "age": 37},
+    {"name": "asghar", "age": 19},
+]
+
+
+@app.get("/", status_code=status.HTTP_200_OK)
+def home_page():
+    return {"msg": "API is working"}
+
+
+@app.get("/users", status_code=status.HTTP_200_OK)
+def show_users():
+    return users
+
+
+@app.post("/create_user", status_code=status.HTTP_201_CREATED)
+def create_user(name: str, age: int):
+    new_user = {"name": name, "age": age}
+    users.append(new_user)
+    return {"msg": f"user {name} with age {age} created"}
+
+
+@app.put("/update_user/{target_name}", status_code=status.HTTP_202_ACCEPTED)
+def update_user(target_name: str, age: int):
+    for user in users:
+        if user["name"] == target_name:
+            user["age"] = age
+            return {"msg": f"user {target_name} updated"}
+    raise HTTPException(
+        status_code=status.HTTP_404_NOT_FOUND,
+        detail="User not found"
+    )
+
+
+@app.delete("/delete_user/{target_name}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_user(target_name: str):
+    for user in users:
+        if user["name"] == target_name:
+            users.remove(user)
+            return
+    raise HTTPException(
+        status_code=status.HTTP_404_NOT_FOUND,
+        detail="User not found"
+    )
+```
+
+---
+
+## Status Code Overview
+
+HTTP status codes communicate the result of an API request to clients and monitoring systems.
+
+| Code | Meaning    | Usage                             |
+| ---- | ---------- | --------------------------------- |
+| 200  | OK         | Successful GET requests           |
+| 201  | Created    | Resource successfully created     |
+| 202  | Accepted   | Update request accepted           |
+| 204  | No Content | Resource deleted successfully     |
+| 404  | Not Found  | Requested resource does not exist |
+
+---
+
+## Endpoint Behavior
+
+### Root Endpoint
+
+```http
+GET /
+```
+
+* Returns HTTP **200 OK**
+* Used as a health check
+
+---
+
+### Create User
+
+```http
+POST /create_user
+```
+
+* Returns HTTP **201 Created**
+* Indicates successful resource creation
+
+---
+
+### Update User
+
+```http
+PUT /update_user/{target_name}
+```
+
+* Returns HTTP **202 Accepted** on success
+* Raises HTTP **404 Not Found** if user does not exist
+
+---
+
+### Delete User
+
+```http
+DELETE /delete_user/{target_name}
+```
+
+* Returns HTTP **204 No Content** on success
+* Returns no response body
+* Raises HTTP **404 Not Found** if user does not exist
+
+---
+
+## Error Handling with `HTTPException`
+
+```python
+raise HTTPException(
+    status_code=status.HTTP_404_NOT_FOUND,
+    detail="User not found"
+)
+```
+
+* Immediately stops request processing
+* Returns structured error responses
+* Automatically serialized by FastAPI
+
+**Error Response Example:**
+
+```json
+{
+  "detail": "User not found"
+}
+```
+
+---
+
+## Example Requests
+
+### Create User
+
+```bash
+curl -X POST "http://localhost:8000/create_user?name=ali&age=25"
+```
+
+### Update User
+
+```bash
+curl -X PUT "http://localhost:8000/update_user/ali?age=30"
+```
+
+### Delete User
+
+```bash
+curl -X DELETE "http://localhost:8000/delete_user/ali"
+```
+
+---
+
+## Running the Application
+
+Start the application using `uvicorn`:
+
+```bash
+uvicorn main:app --reload
+```
+
+---
+
+## Best Practices
+
+* Always return meaningful HTTP status codes
+* Use `status` module instead of hard-coded numbers
+* Use `HTTPException` for predictable error handling
+* Do not return response bodies with `204 No Content`
+* Align status codes with REST conventions
+* Ensure monitoring systems rely on status codes, not messages
+* Standardize error formats across services
+