آپ routes (path operations) کو کیسے define کرتے ہیں؟

Question

Accepted Answer

FastAPI میں، ایک **path operation** ایک route ہے — ایک function جو HTTP method decorator (`@app.get`, `@app.post`, وغیرہ) سے سجایا گیا ہو جو ایک path پر requests کو سنبھالتا ہے۔ Function کی return value خود بخود JSON میں serialize ہو جاتی ہے۔

## ہر HTTP method کے لیے routes define کرنا

```python
from fastapi import FastAPI
app = FastAPI()

@app.get("/items")                # GET /items
def list_items():
    return [{"id": 1}, {"id": 2}]  # dict/list → automatically JSON-serialized

@app.get("/items/{item_id}")      # GET /items/5 — path parameter
def get_item(item_id: int):        # type hint converts "5" → int (and validates)
    return {"id": item_id}

@app.post("/items")               # POST /items
def create_item(item: Item):
    return item

@app.put("/items/{item_id}")      # PUT, PATCH, DELETE work the same way
@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    return {"deleted": item_id}
```

ہر decorator ایک HTTP method + path کو ایک handler سے map کرتا ہے۔ Function کا نام آپ کا اپنا ہے؛ decorator route کو define کرتا ہے۔ Return کیے گئے dicts/lists/Pydantic models خود بخود JSON میں serialize ہو جاتے ہیں — کوئی manual `json.dumps` نہیں۔

## Overlapping paths کے لیے ترتیب اہم ہے

```python
@app.get("/users/me")            # ✅ specific route FIRST
def read_me(): ...
@app.get("/users/{user_id}")     # dynamic AFTER — else "me" matches {user_id}
def read_user(user_id: int): ...
```

FastAPI routes کو declaration کی ترتیب میں match کرتا ہے، اس لیے static paths کو dynamic ones سے پہلے رکھیں۔

## Operation metadata (docs کو drive کرتا ہے)

```python
@app.get("/items", tags=["items"], summary="List items", status_code=200)
def list_items(): ...
```

Decorator parameters (`tags`, `summary`, `status_code`, `response_model`) behavior کو configure کرتے ہیں اور auto-generated documentation کو بہتر بناتے ہیں۔

## یہ کیوں اہم ہے

Path operations ہر FastAPI application کی بنیاد ہیں — وہ آپ کے API کے endpoints اور requests کو کیسے سنبھالا جاتا ہے اس کو define کرتے ہیں۔

Decorator-per-HTTP-method pattern کو سمجھنا، کہ return values خود بخود JSON میں serialize ہوتی ہیں (کوئی boilerplate نہیں)، کہ parameters پر type hints conversion اور validation کو drive کرتے ہیں، اور کہ overlapping paths کے لیے route order اہم ہے — یہ کسی بھی endpoint کو بنانے کے لیے روزمرہ کا لازمی علم ہے۔

Decorator metadata بھی FastAPI کی automatic documentation کو feed کرتی ہے، routes کو براہ راست docs سے جوڑتے ہوئے۔

یہ FastAPI میں سیکھنے کا پہلا اور سب سے بنیادی چیز ہے۔