Unawezaje kusanidi CORS katika FastAPI?

Question

Accepted Answer

**CORS** (Cross-Origin Resource Sharing) ni mfumo wa usalama wa kivinjari unaodhibiti iwapo ukurasa wa wavuti kutoka **origin** moja unaweza kuita API yako kwenye origin tofauti. FastAPI huisanidi kwa **`CORSMiddleware`** iliyojengwa ndani. Utakutana na CORS kila wakati frontend iliyo kwenye domain/port tofauti inapoita API yako.

## Tatizo ambalo CORS hushughulikia

```text
A React app at http://localhost:3000 calling an API at http://localhost:8000 is
CROSS-ORIGIN (different port). The BROWSER blocks the response unless the API
sends CORS headers permitting that origin.
(origin = scheme + host + port)
```

## Kusanidi CORSMiddleware

```python
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com", "http://localhost:3000"],  # ALLOWLIST of origins
    allow_credentials=True,         # allow cookies/auth (requires specific origins, not "*")
    allow_methods=["*"],             # or ["GET", "POST", ...]
    allow_headers=["*"],
)
```

Middleware huongeza CORS response headers zinazohitajika, ikiarifu kivinjari ni origins, methods, na headers zipi zinaruhusiwa. Kivinjari hutekeleza sheria hizi.

## Usalama: zuia origins (usitumie "*")

```python
# ❌ allowing all origins — convenient but insecure for credentialed/private APIs
allow_origins=["*"]
# ✅ restrict to your known frontend origins (an allowlist)
allow_origins=["https://app.example.com"]
# NOTE: allow_credentials=True is INCOMPATIBLE with allow_origins=["*"]
```

Kwa uzalishaji, **zuia `allow_origins` kwa allowlist** badala ya `*`. Pia, kuruhusu credentials (cookies/auth) kunahitaji origins mahususi — wildcard hairuhusiwi pamoja na credentials.

## Dhana potofu muhimu

```text
CORS is enforced by the BROWSER, not the server. It does NOT protect your API from
non-browser clients (curl, Postman, other servers) — those ignore CORS entirely.
CORS only governs what browser JavaScript from other origins may do.
```

## Kwa nini ni muhimu

CORS ni mojawapo ya vikwazo vinavyokutana sana katika maendeleo ya wavuti — karibu kila usanidi wa frontend-kwenda-API hukutana nao (hasa katika maendeleo ya ndani yenye ports tofauti, na katika uzalishaji yenye domain tofauti ya frontend), kwa hivyo kujua jinsi ya kuisanidi kwa `CORSMiddleware` ya FastAPI ni maarifa ya vitendo yanayohitajika mara kwa mara.

Kuelewa *kwa nini* ipo (usalama wa same-origin wa kivinjari), jinsi seva inavyojisajili kupitia response headers, na jinsi ya kuisanidi (origins zinazoruhusiwa, methods, headers, credentials) ni muhimu kuunganisha frontends na API za FastAPI bila maombi kuzuiwa.

Muhimu vile vile ni kuisanidi **kwa usalama** — kuzuia `allow_origins` kwa allowlist mahususi badala ya `*` iliyo huru (na kuelewa kuwa credentials hazioani na wildcard) — na kufahamu dhana potofu muhimu kwamba **CORS ni mfumo wa kivinjari, si idhini ya API** (hailindi dhidi ya clients zisizo za kivinjari).

Kujua jinsi ya kuweka CORS kwa usahihi na kwa usalama ni maarifa muhimu ya kila siku kwa API yoyote ya FastAPI inayotumiwa na frontend ya wavuti.