CORSMiddleware: Unblocking Your Frontend from Your Backend

WHY IT EXISTS: Browsers enforce a "Same-Origin Policy" by default. This security measure prevents a script on a malicious website from making requests to another website where you might be logged in, like your bank or email. CORS (Cross-Origin Resource Sharing) is the standard mechanism for a server to tell a browser it's safe to relax this policy for specific, trusted origins.

THE MENTAL MODEL: Think of your API as a private club and the browser as its bouncer. When your frontend code (a guest) tries to enter, the bouncer asks for its address (its origin). The bouncer then checks a guest list provided by the club owner (your API's CORSMiddleware configuration). If the frontend's origin is on the list, it's allowed in. If not, the bouncer denies entry, and the browser reports a CORS error. The key is that the bouncer (browser) enforces the rule, but the club (server) sets the policy.

HOW IT WORKS: When a frontend on http://localhost:3000 tries to make a request to a backend on http://localhost:8000, the browser first sends a special "preflight" request (HTTP OPTIONS). FastAPI's CORSMiddleware intercepts this. If http://localhost:3000 is in the configured allow_origins list, the middleware responds with permission headers like Access-Control-Allow-Origin. Seeing this, the browser then sends the actual GET or POST request.

WHEN TO USE IT: Use CORSMiddleware any time your API will be accessed by a JavaScript frontend running in a browser that is served from a different origin. This is the standard setup for modern Single-Page Applications (SPAs) built with frameworks like React, Vue, or Angular. Even if the domain is the same (localhost), a different port number makes it a different origin.

WHEN NOT TO USE IT: You don't need to configure CORS if your API is only used by non-browser clients like mobile apps, other backend services, or command-line scripts. These clients do not enforce the Same-Origin Policy. You also don't need it in a monolithic application where the frontend and API are served from the exact same origin.

ONE CANONICAL EXAMPLE: In your FastAPI application, you add the middleware and configure it with a list of trusted frontend origins. A typical setup looks like this: origins = ["http://localhost:3000", "https://your-app.com"]. Then you add the middleware to your app instance: app.add_middleware(CORSMiddleware, allow_origins=origins, allow_credentials=True, allow_methods=[""], allow_headers=[""]). This explicitly tells browsers that frontends from those two origins are permitted to make requests.