Preflight Requests in FastAPI | CodeSignal Learn

Preflight Requests in FastAPI | CodeSignal Learn

Introduction

Welcome back! In our previous lesson, we explored the basics of Cross-Origin Resource Sharing (CORS) and its significance in web development. Now, we're going to dive deeper into a crucial aspect of CORS: preflight requests . These requests play a vital role in ensuring secure cross-origin communication. Think of them as a security check before allowing access to resources. By the end of this lesson, you'll understand what preflight requests are, when they occur, and how to handle them effectively in your Python REST API using FastAPI. Let's get started! 🚀

Understanding Preflight Requests

Preflight requests are a part of the CORS mechanism that browsers use to determine if a cross-origin request is safe to send. They are triggered when a request uses methods other than simple methods like GET, HEAD, or POST (with certain content types), or when custom headers are included. To be more specific, POST requests are only considered "simple" if they use one of the following content types: application/x-www-form-urlencoded, multipart/form-data, or text/plain . If a POST request uses application/json—which is common in modern APIs—it will trigger a preflight request. This is an important detail that explains why many seemingly normal API requests may involve a preflight check. Here's how preflight requests work: When you make a "non-simple" cross-origin request, the browser first sends an OPTIONS request to the server This preflight request checks if the actual request is allowed based on origin, method, and headers The server responds with specific CORS headers indicating what's permitted Only if the preflight is successful will the browser send the actual request Imagine you're entering a secure building; a preflight request is like the security guard checking your credentials before letting you in. Without proper handling of these preflight requests, certain cross-origin requests will be blocked by browsers.

Why Preflight Requests Matter

To understand why we need to handle preflight requests properly, let's look at a common scenario: Suppose your frontend (running on http://localhost:3000) needs to make a PUT request to your API (running on http://localhost:8000) with a custom Authorization header. Before sending the actual PUT request, the browser will automatically send an OPTIONS request to check if: The server allows requests from http://localhost:3000 (origin) The server allows PUT methods The server accepts the Authorization header If your server doesn't properly respond to this OPTIONS request with the appropriate CORS headers, the browser will block the actual PUT request, and you'll see an error like: plaintext Access to fetch at 'http://localhost:8000/api/resource' from origin 'http://localhost:3000' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Setting Up Preflight Handling: Basic Configuration

Let's implement proper preflight request handling in our Python REST API using FastAPI: Pythonfrom fastapi import FastAPI, Request from starlette.middleware.base import BaseHTTPMiddleware from starlette.responses import Response from typing import List, Optional app = FastAPI() class CustomCORSMiddleware(BaseHTTPMiddleware): def __init__(self, app, allowed_origins: List[str] = None, allowed_methods: List[str] = None, allowed_headers: List[str] = None, allow_credentials: bool = True, max_age: int = 600): super().__init__(app) self.allowed_origins = allowed_origins or ['http://localhost:3000'] self.allowed_methods = allowed_methods or ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'] self.allowed_headers = allowed_headers or ['Content-Type', 'Authorization', 'X-Requested-With'] self.allow_credentials = allow_credentials self.max_age = max_age def _is_origin_allowed(self, origin: str) -> bool: return origin in self.allowed_origins async def dispatch(self, request: Request, call_next): origin = request.headers.get('origin') method = request.method # Handle preflight requests (OPTIONS) if method == 'OPTIONS' and origin: if self._is_origin_allowed(origin): response = Response(status_code=204) # No Content for preflight response.headers['Access-Control-Allow-Origin'] = origin response.headers['Access-Control-Allow-Methods'] = ', '.join(self.allowed_methods) response.headers['Access-Control-Allow-Headers'] = ', '.join(self.allowed_headers) response.headers['Access-Control-Max-Age'] = str(self.max_age) if self.allow_credentials: response.headers['Access-Control-Allow-Credentials'] = 'true' return response # Process the actual request response = await call_next(request) # Add CORS headers to actual responses if origin and self._is_origin_allowed(origin): response.headers['Access-Control-Allow-Origin'] = origin if self.allow_credentials: response.headers['Access-Control-Allow-Credentials'] = 'true' return response # Apply CORS middleware to handle preflight requests app.add_middleware(CustomCORSMiddleware, allowed_origins=['http://localhost:3000'], allowed_methods=['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'], allowed_headers=['Content-Type', 'Authorization', 'X-Requested-With'], allow_credentials=True, max_age=600) # Cache preflight response for 10 minutes # Your routes here @app.get('/api/resources') async def get_resources(): return {'message': 'This is a GET endpoint'} @app.put('/api/resources/{resource_id}') async def update_resource(resource_id: int): return {'message': 'This is a PUT endpoint'} if __name__ == '__main__': import uvicorn uvicorn.run(app, host='0.0.0.0', port=8000) When a browser sends a preflight request to this server, the CORS middleware automatically responds with the following headers: plaintextAccess-Control-Allow-Origin: http://localhost:3000 Access-Control-Allow-Methods: GET,POST,PUT,DELETE,PATCH,OPTIONS Access-Control-Allow-Headers: Content-Type,Authorization,X-Requested-With Access-Control-Allow-Credentials: true Access-Control-Max-Age: 600 The browser uses these headers to determine if the actual request is allowed. The max_age parameter tells browsers how long (in seconds) they can cache the preflight response, reducing the number of preflight requests and improving performance. Note: However, not all browsers respect the max_age setting equally. For example, some versions of Safari have been known to ignore this header, resulting in more frequent preflight requests than expected.

Setting Up Preflight Handling: Route-Specific CORS Policies

Sometimes, you might want different CORS policies for different routes. Here's how to create middleware for specific route types: Pythonfrom fastapi import FastAPI, APIRouter, Request from starlette.middleware.base import BaseHTTPMiddleware from starlette.responses import Response, JSONResponse from typing import List, Dict, Optional def create_preflight_handler(allowed_origins: List[str], allowed_methods: List[str] = None, allowed_headers: List[str] = None, max_age: int = 600): """Create a CORS middleware with specific configuration""" if allowed_methods is None: allowed_methods = ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'] if allowed_headers is None: allowed_headers = ['Content-Type', 'Authorization'] class SpecificCORSMiddleware(BaseHTTPMiddleware): def __init__(self, app): super().__init__(app) def _is_origin_allowed(self, origin: str) -> bool: return origin in allowed_origins async def dispatch(self, request: Request, call_next): origin = request.headers.get('origin') method = request.method # Handle preflight requests (OPTIONS) if method == 'OPTIONS' and origin: if self._is_origin_allowed(origin): response = Response(status_code=204) response.headers['Access-Control-Allow-Origin'] = origin response.headers['Access-Control-Allow-Methods'] = ', '.join(allowed_methods) response.headers['Access-Control-Allow-Headers'] = ', '.join(allowed_headers) response.headers['Access-Control-Max-Age'] = str(max_age) response.headers['Access-Control-Allow-Credentials'] = 'true' return response else: return JSONResponse( content={'error': f'Origin {origin} not allowed'}, status_code=403 ) # Process the actual request response = await call_next(request) # Add CORS headers to actual responses if origin and self._is_origin_allowed(origin): response.headers['Access-Control-Allow-Origin'] = origin response.headers['Access-Control-Allow-Credentials'] = 'true' return response return SpecificCORSMiddleware # Create the main app app = FastAPI() # Create FastAPI sub-applications with different CORS policies public_app = FastAPI() public_app.add_middleware(create_preflight_handler( allowed_origins=['http://localhost:3000', 'https://public-app.example.com'], allowed_methods=['GET', 'OPTIONS'] )) auth_app = FastAPI() auth_app.add_middleware(create_preflight_handler( allowed_origins=['http://localhost:3000'], allowed_methods=['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'] )) admin_app = FastAPI() admin_app.add_middleware(create_preflight_handler( allowed_origins=['https://admin.example.com'], allowed_methods=['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'] )) # Define routes on each app @public_app.get('/resources') async def get_public_resources(): return {'message': 'Public resources'} @auth_app.put('/user/{user_id}') async def update_user(user_id: int): return {'message': 'User updated'} # Mount sub-applications with different CORS configurations app.mount('/api/public', public_app) app.mount('/api/auth', auth_app) app.mount('/api/admin', admin_app) if __name__ == '__main__': import uvicorn uvicorn.run(app, host='0.0.0.0', port=8000) This implementation provides fine-grained control over which origins, methods, and headers are allowed for different parts of your API. Each route type can have its own preflight handling configuration.

Setting Up Preflight Handling: Adding Preflight Logging and Diagnostics

To make debugging easier, let's add middleware to log preflight requests: Pythonfrom fastapi import Request from starlette.middleware.base import BaseHTTPMiddleware from starlette.responses import Response import json from datetime import datetime class PreflightLoggerMiddleware(BaseHTTPMiddleware): """Middleware to log preflight requests for debugging purposes""" async def dispatch(self, request: Request, call_next): if request.method == 'OPTIONS': print(f"[PREFLIGHT] {datetime.now().isoformat()} - {request.method} {request.url.path}") print(f" Origin: {request.headers.get('origin')}") print(f" Requested Method: {request.headers.get('access-control-request-method')}") print(f" Requested Headers: {request.headers.get('access-control-request-headers')}") # Process the request response = await call_next(request) # Log response headers print(" Responding with CORS headers:") print(f" Access-Control-Allow-Origin: {response.headers.get('Access-Control-Allow-Origin')}") print(f" Access-Control-Allow-Methods: {response.headers.get('Access-Control-Allow-Methods')}") print(f" Access-Control-Allow-Headers: {response.headers.get('Access-Control-Allow-Headers')}") print(f" Access-Control-Max-Age: {response.headers.get('Access-Control-Max-Age')}") return response return await call_next(request) # Apply the logger middleware before CORS middleware app = FastAPI() app.add_middleware(PreflightLoggerMiddleware) app.add_middleware(CustomCORSMiddleware, allowed_origins=['http://localhost:3000'], max_age=600) @app.get('/api/resources/{resource_id}') async def get_resource(resource_id: int): return {'message': f'Resource {resource_id}'} When a preflight request comes in, this middleware will log information like: plaintext[PREFLIGHT] 2023-11-21T14:35:22.657000 - OPTIONS /api/resources/123 Origin: http://localhost:3000 Requested Method: PUT Requested Headers: content-type,authorization Responding with CORS headers: Access-Control-Allow-Origin: http://localhost:3000 Access-Control-Allow-Methods: GET,POST,PUT,DELETE,PATCH,OPTIONS Access-Control-Allow-Headers: Content-Type,Authorization,X-Requested-With Access-Control-Max-Age: 600 This detailed logging helps you understand exactly what's happening with preflight requests and troubleshoot any CORS issues.

Manually Handling Preflight Requests Without CORS Middleware

While middleware handles preflight requests automatically, understanding how to handle them manually provides deeper insight: Pythonfrom fastapi import FastAPI, Request from starlette.responses import Response app = FastAPI() @app.options('/{full_path:path}') async def handle_preflight(request: Request): """Manual preflight handler for all routes""" response = Response(status_code=204) # No Content for preflight # Set CORS headers response.headers['Access-Control-Allow-Origin'] = 'http://localhost:3000' response.headers['Access-Control-Allow-Methods'] = 'GET,PUT,POST,DELETE,OPTIONS' response.headers['Access-Control-Allow-Headers'] = 'Content-Type,Authorization' response.headers['Access-Control-Max-Age'] = '600' response.headers['Access-Control-Allow-Credentials'] = 'true' return response @app.middleware("http") async def add_cors_headers(request: Request, call_next): """Add CORS headers to all responses""" response = await call_next(request) # Add CORS headers to actual responses response.headers['Access-Control-Allow-Origin'] = 'http://localhost:3000' response.headers['Access-Control-Allow-Credentials'] = 'true' return response # Your routes @app.get('/api/resources') async def get_resources(): return {'message': 'Resources retrieved'} if __name__ == '__main__': import uvicorn uvicorn.run(app, host='0.0.0.0', port=8000) This manual approach gives you complete control over how preflight requests are handled, but requires more maintenance than using middleware.

Common Pitfalls and Misconceptions

When handling preflight requests in Python/FastAPI, there are several common pitfalls to avoid: Ignoring OPTIONS requests : Some developers forget to handle OPTIONS requests, causing preflight requests to fail. FastAPI middleware handles this automatically, but if you're building custom middleware, you need to respond to OPTIONS requests correctly. Misunderstanding preflight caching : Setting an appropriate max_age value can significantly improve performance by reducing redundant preflight requests. However, setting it too high might cause issues if you need to change CORS policies. Forgetting credentials : If your API uses cookies or authentication headers, you need to set allow_credentials=True and ensure your Access-Control-Allow-Origin is not set to a wildcard (*). Insufficient method allowance : Remember that the preflight request is checking what methods are allowed. If you don't include all methods your API needs in the allowed methods list, certain operations will fail. Incorrectly responding to manual OPTIONS requests : If you handle OPTIONS requests manually (without middleware), you must include all necessary CORS headers: Access-Control-Allow-Origin, Access-Control-Allow-Methods, and Access-Control-Allow-Headers . Additionally, you should respond with a 204 (No Content) status code rather than 200, as shown in our manual example. Failing to include required headers or returning the wrong status code will cause the browser to reject the actual request. Middleware order matters : In FastAPI, middleware is executed in reverse order of how it's added. Make sure your CORS middleware runs before other middleware that might interfere with the response.

Conclusion and Next Steps

In this lesson, we explored preflight requests, a crucial aspect of the CORS mechanism. We learned how browsers use preflight requests to ensure secure cross-origin communication and how to properly configure our Python REST API using FastAPI to handle these requests. We implemented both automatic middleware-based and manual preflight handling systems with route-specific configurations and diagnostic logging to help troubleshoot issues. Understanding and correctly implementing preflight request handling is essential for building secure, well-functioning APIs that can be accessed by web applications across different origins. In the upcoming practice exercises, you'll have the opportunity to apply what you've learned and strengthen your understanding of preflight requests. In our next lesson, we'll continue to enhance the security of your Python REST API with more advanced CORS configurations. Keep up the great work! 🌟

Previous Lesson Next Lesson: Cross Origin Cookie Authentication

Sign up

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal