fastapi doc : body post doc

Docs/Services/FastAPI/11-Post-Types.md

@@ -0,0 +1,226 @@
+# POST Request Types and Content Types
+
+This document explains the **body types of POST requests** and the most common **Content-Types** used in APIs.
+Understanding these formats is essential for building interoperable and production-ready FastAPI services.
+
+---
+
+## POST Request Body Types
+
+A POST request sends data to the server in the **request body**.
+The format of this data is defined by the **Content-Type** header.
+
+---
+
+## 1. Form Data
+
+### Description
+
+Used primarily for HTML form submissions. Common in browser-based applications.
+
+### Content-Type
+
+```
+application/x-www-form-urlencoded
+```
+
+or
+
+```
+multipart/form-data
+```
+
+### Characteristics
+
+* Key-value pairs
+* Supports file uploads (multipart)
+* Common in login and upload forms
+
+### Example
+
+```http
+POST /login
+Content-Type: application/x-www-form-urlencoded
+
+username=admin&password=secret
+```
+
+---
+
+## 2. JSON
+
+### Description
+
+The most common data format for REST APIs.
+
+### Content-Type
+
+```
+application/json
+```
+
+### Characteristics
+
+* Structured, readable, and language-independent
+* Easily parsed and validated
+* Default choice for FastAPI APIs
+
+### Example
+
+```json
+{
+  "name": "abbas",
+  "age": 25
+}
+```
+
+---
+
+## 3. XML
+
+### Description
+
+An older but still widely used data format in enterprise systems and legacy APIs.
+
+### Content-Type
+
+```
+application/xml
+```
+
+or
+
+```
+text/xml
+```
+
+### Characteristics
+
+* Verbose and schema-driven
+* Common in SOAP-based services
+* Less common in modern REST APIs
+
+### Example
+
+```xml
+<user>
+  <name>abbas</name>
+  <age>25</age>
+</user>
+```
+
+---
+
+## 4. Plain Text
+
+### Description
+
+Used when sending raw text without structure.
+
+### Content-Type
+
+```
+text/plain
+```
+
+### Characteristics
+
+* No schema or structure
+* Useful for logs, messages, or simple payloads
+* Requires custom parsing on the server
+
+### Example
+
+```
+Hello FastAPI
+```
+
+---
+
+## 5. Binary Data
+
+### Description
+
+Used for sending non-textual data such as images, videos, or files.
+
+### Content-Type
+
+```
+application/octet-stream
+```
+
+### Characteristics
+
+* Raw binary format
+* Common for file uploads and downloads
+* Requires stream handling
+
+### Example
+
+```
+(binary file data)
+```
+
+---
+
+## 6. GraphQL
+
+### Description
+
+GraphQL uses POST requests to execute queries and mutations.
+
+### Content-Type
+
+```
+application/json
+```
+
+### Characteristics
+
+* Single endpoint
+* Flexible client-driven queries
+* Requires GraphQL server support
+
+### Example
+
+```json
+{
+  "query": "query { users { id name } }"
+}
+```
+
+---
+
+## Common Content Types Summary
+
+| Content-Type                        | Usage                      |
+| ----------------------------------- | -------------------------- |
+| `application/json`                  | REST APIs (default)        |
+| `application/x-www-form-urlencoded` | HTML forms                 |
+| `multipart/form-data`               | Forms with file uploads    |
+| `application/xml`                   | Legacy / SOAP APIs         |
+| `text/plain`                        | Raw text                   |
+| `application/octet-stream`          | Binary data                |
+| `application/graphql`               | GraphQL (rare, often JSON) |
+
+---
+
+## FastAPI Considerations
+
+* JSON is the recommended default for FastAPI
+* Use Pydantic models for JSON validation
+* Use `Form()` and `File()` for form and file uploads
+* Always validate content type in production APIs
+* Document supported content types clearly
+
+---
+
+## Best Practices
+
+* Choose the simplest format that meets requirements
+* Prefer `application/json` for APIs
+* Avoid XML unless required by integration
+* Secure file uploads (size limits, scanning)
+* Validate all incoming request bodies
+* Be explicit about supported Content-Types
+

Docs/Services/FastAPI/12-From-Post.md

@@ -0,0 +1,165 @@
+# FastAPI – POST Requests with Form Data
+
+This document demonstrates how to handle **form-based POST requests** in FastAPI using the `Form()` dependency.
+Form data is commonly used in **HTML forms**, authentication flows, and legacy systems.
+
+---
+
+## Example Application
+
+Create or update `main.py` with the following content:
+
+```python
+from fastapi import FastAPI, Form, status
+from fastapi.responses import JSONResponse
+
+app = FastAPI()
+
+users_db = [
+    {"id": "1", "name": "radin", "password": "123"}
+]
+
+
+@app.post("/user/")
+def get_user_from_form(
+    target: int = Form(
+        ...,
+        gt=0,
+        alias="User ID",
+        description="Enter target unique ID",
+    )
+):
+    for item in users_db:
+        if item["id"] == str(target):
+            return JSONResponse(
+                content={"msg": f"Your target user name is {item['name']}"},
+                status_code=status.HTTP_200_OK,
+            )
+
+    return JSONResponse(
+        content={"msg": "user not found"},
+        status_code=status.HTTP_404_NOT_FOUND,
+    )
+```
+
+---
+
+## Form Data Overview
+
+### What is Form Data
+
+Form data is sent in the request body using:
+
+```
+Content-Type: application/x-www-form-urlencoded
+```
+
+or
+
+```
+multipart/form-data
+```
+
+FastAPI requires the `Form()` dependency to explicitly declare form inputs.
+
+---
+
+## Endpoint Behavior
+
+### Endpoint
+
+```http
+POST /user/
+```
+
+### Request Body (Form Data)
+
+```
+User ID=1
+```
+
+### Example Using `curl`
+
+```bash
+curl -X POST "http://localhost:8000/user/" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "User ID=1"
+```
+
+---
+
+## Response Examples
+
+### Success Response
+
+```json
+{
+  "msg": "Your target user name is radin"
+}
+```
+
+Status Code: **200 OK**
+
+---
+
+### Failure Response
+
+```json
+{
+  "msg": "user not found"
+}
+```
+
+Status Code: **404 Not Found**
+
+---
+
+## `Form()` Parameter Configuration
+
+```python
+Form(
+    ...,
+    gt=0,
+    alias="User ID",
+    description="Enter target unique ID"
+)
+```
+
+| Parameter     | Description                     |
+| ------------- | ------------------------------- |
+| `...`         | Field is required               |
+| `gt=0`        | Value must be greater than zero |
+| `alias`       | Custom form field name          |
+| `description` | Displayed in API docs           |
+
+---
+
+## Swagger / OpenAPI Behavior
+
+* Form fields appear as input fields
+* Aliases are reflected in the UI
+* Validation rules are enforced automatically
+* Errors are returned with clear messages
+
+---
+
+## Running the Application
+
+Start the service using `uvicorn`:
+
+```bash
+uvicorn main:app --reload
+```
+
+---
+
+## Best Practices
+
+* Use form data only when required (e.g. HTML forms)
+* Prefer JSON for APIs and services
+* Avoid exposing sensitive fields in plain form data
+* Use HTTPS for all form submissions
+* Validate and sanitize all inputs
+* Use authentication and hashing for passwords
+* Do not store credentials in plain text
+

Docs/Services/FastAPI/13-Body-Post.md

@@ -0,0 +1,161 @@
+# FastAPI – POST Requests with JSON Body (`Body`)
+
+This document demonstrates how to receive data from the **request body** using `Body()` in FastAPI.
+This approach is commonly used when clients send **JSON payloads**.
+
+---
+
+## Example Application
+
+Create or update `main.py` with the following content:
+
+```python
+from fastapi import FastAPI, Body, status
+from fastapi.responses import JSONResponse
+
+app = FastAPI()
+
+users_db = [
+    {"id": "1", "name": "radin", "password": "123"}
+]
+
+
+@app.post("/user/")
+def get_user_from_body(
+    target: int = Body(
+        ...,
+        embed=True,
+        gt=0,
+        alias="User ID",
+        description="Enter target unique ID",
+    )
+):
+    for item in users_db:
+        if item["id"] == str(target):
+            return JSONResponse(
+                content={"msg": f"Your target user name is {item['name']}"},
+                status_code=status.HTTP_200_OK,
+            )
+
+    return JSONResponse(
+        content={"msg": "user not found"},
+        status_code=status.HTTP_404_NOT_FOUND,
+    )
+```
+
+---
+
+## JSON Body Overview
+
+### What Is a Request Body
+
+The request body contains structured data sent by the client, most commonly as **JSON**.
+
+**Content-Type:**
+
+```
+application/json
+```
+
+---
+
+## Request Format
+
+### Example JSON Payload
+
+```json
+{
+  "User ID": 1
+}
+```
+
+* `embed=True` requires the value to be wrapped inside a JSON object
+* The key name is controlled by the `alias`
+
+---
+
+## Example Request Using `curl`
+
+```bash
+curl -X POST "http://localhost:8000/user/" \
+  -H "Content-Type: application/json" \
+  -d '{"User ID": 1}'
+```
+
+---
+
+## Response Examples
+
+### Success Response
+
+```json
+{
+  "msg": "Your target user name is radin"
+}
+```
+
+Status Code: **200 OK**
+
+---
+
+### Failure Response
+
+```json
+{
+  "msg": "user not found"
+}
+```
+
+Status Code: **404 Not Found**
+
+---
+
+## `Body()` Parameter Configuration
+
+```python
+Body(
+    ...,
+    embed=True,
+    gt=0,
+    alias="User ID",
+    description="Enter target unique ID"
+)
+```
+
+| Parameter     | Purpose                          |
+| ------------- | -------------------------------- |
+| `...`         | Field is required                |
+| `embed=True`  | Wraps the value in a JSON object |
+| `gt=0`        | Validates input value            |
+| `alias`       | Custom JSON key name             |
+| `description` | Shown in API documentation       |
+
+---
+
+## Swagger / OpenAPI Behavior
+
+* JSON schema is automatically generated
+* Validation errors are returned if rules are violated
+* Aliases and descriptions appear in Swagger UI
+* Request body is clearly documented
+
+---
+
+## Running the Application
+
+Start the service using `uvicorn`:
+
+```bash
+uvicorn main:app --reload
+```
+
+---
+
+## Best Practices
+
+* Prefer request body over query parameters for POST requests
+* Use Pydantic models instead of raw `Body()` for complex payloads
+* Keep JSON structures consistent
+* Avoid spaces in JSON keys for production APIs
+* Never send sensitive data in plain text
+* Use HTTPS for all JSON-based APIs