flask-restful — Cursor rule for Flask APIs

---
description: This guide defines definitive best practices for building robust, maintainable, and modern REST APIs using Flask-RESTful, emphasizing Pydantic for validation and clear architectural patterns.
globs: **/*.py
---
# flask-restful Best Practices

Flask-RESTful provides a lightweight foundation for REST APIs. To build modern, scalable, and maintainable services in 2025, we augment its core with established Python best practices, focusing on type safety, clear separation of concerns, and robust data handling.

## 1. Code Organization and Structure

Always structure your application for modularity and testability. Use Flask Blueprints to organize API versions or domains.

### ✅ GOOD: Modular Project Structure with Blueprints

Organize your application into logical packages:

```
.
├── app/
│   ├── __init__.py         # Flask app creation, API initialization
│   ├── api/
│   │   ├── __init__.py     # Blueprint definition
│   │   ├── v1/
│   │   │   ├── __init__.py # Register resources to v1 blueprint
│   │   │   ├── resources.py# API Resource classes
│   │   │   └── services.py # Business logic for v1
│   ├── schemas.py          # Pydantic models for input/output
│   ├── models.py           # SQLAlchemy/SQLModel ORM definitions
│   └── errors.py           # Custom exception classes
├── config.py
├── run.py                  # Application entry point
└── requirements.txt
```

**`app/__init__.py`**:

```python
from flask import Flask
from flask_restful import Api
from config import Config
from app.api import api_bp # Import the blueprint

def create_app():
    app = Flask(__name__)
    app.config.from_object(Config)

    # Register API blueprint
    app.register_blueprint(api_bp, url_prefix='/api')

    # Centralized error handling (see section 3)
    from app.errors import register_error_handlers
    register_error_handlers(app)

    return app
```

**`app/api/__init__.py`**:

```python
from flask import Blueprint
from flask_restful import Api

api_bp = Blueprint('api', __name__)
api = Api(api_bp)

# Import and register resources from v1
from app.api.v1 import register_v1_resources
register_v1_resources(api)
```

**`app/api/v1/__init__.py`**:

```python
from flask_restful import Api

def register_v1_resources(api: Api):
    from .resources import UserResource, UserListResource
    api.add_resource(UserListResource, '/v1/users')
    api.add_resource(UserResource, '/v1/users/<int:user_id>')
```

## 2. Request/Response Patterns: Pydantic for Validation and Serialization

**NEVER** use `flask_restful.reqparse` for complex input validation or `flask_restful.fields` for output serialization. These are outdated and lack type safety. **ALWAYS** use Pydantic for robust, type-checked data handling.

### ❌ BAD: `reqparse` and `fields`

```python
# app/api/v1/resources.py (BAD)
from flask_restful import Resource, reqparse, fields, marshal_with

user_fields = {
    'id': fields.Integer,
    'name': fields.String,
    'email': fields.String,
}

class UserResource(Resource):
    @marshal_with(user_fields)
    def get(self, user_id):
        # ... fetch user ...
        return user

    def post(self):
        parser = reqparse.RequestParser()
        parser.add_argument('name', type=str, required=True, help='Name is required')
        parser.add_argument('email', type=str, required=True, help='Email is required')
        args = parser.parse_args()
        # ... create user ...
        return {'message': 'User created'}, 201
```

### ✅ GOOD: Pydantic for Input Validation and Output Serialization

Pydantic provides clear, declarative schemas, automatic validation, and excellent integration with type checkers.

**`app/schemas.py`**:

```python
from pydantic import BaseModel, Field, EmailStr
from typing import Optional

class UserCreateSchema(BaseModel):
    name: str = Field(..., min_length=1, description="User's full name")
    email: EmailStr = Field(..., description="User's email address")

class UserResponseSchema(BaseModel):
    id: int = Field(..., description="Unique user identifier")
    name: str
    email: EmailStr
    is_active: bool = True

    class Config:
        from_attributes = True # Allow Pydantic to read ORM attributes
```

**`app/api/v1/resources.py`**:

```python
from flask import request
from flask_restful import Resource
from app.schemas import UserCreateSchema, UserResponseSchema
from app.api.v1.services import UserService # Business logic

class UserListResource(Resource):
    def post(self):
        try:
            # Validate input using Pydantic
            user_data = UserCreateSchema.parse_obj(request.json)
            user = UserService.create_user(user_data)
            # Serialize output using Pydantic
            return UserResponseSchema.from_orm(user).dict(), 201
        except ValueError as e: # Pydantic validation errors
            return {'message': str(e)}, 400

class UserResource(Resource):
    def get(self, user_id: int):
        user = UserService.get_user(user_id)
        if not user:
            return {'message': 'User not found'}, 404
        return UserResponseSchema.from_orm(user).dict(), 200
```

## 3. Error Handling

Centralize error handling to provide consistent, informative JSON responses.

### ✅ GOOD: Custom Exceptions and Centralized Handling

Define custom exceptions and register them with Flask's `app.register_error_handler` or Flask-RESTful's `api.handle_error` (or `error_router` if using Flask-RESTX).

**`app/errors.py`**:

```python
from flask import Flask, jsonify
from werkzeug.exceptions import HTTPException

class APIError(HTTPException):
    code = 500
    description = 'An unexpected error occurred.'

    def __init__(self, message: str = None, code: int = None, payload: dict = None):
        if message:
            self.description = message
        if code:
            self.code = code
        self.payload = payload
        super().__init__(description=self.description)

    def get_response(self, environment=None):
        response = jsonify({
            'message': self.description,
            'status_code': self.code,
            'payload': self.payload
        })
        response.status_code = self.code
        return response

class NotFoundError(APIError):
    code = 404
    description = 'Resource not found.'

class BadRequestError(APIError):
    code = 400
    description = 'Invalid request payload.'

def register_error_handlers(app: Flask):
    @app.errorhandler(APIError)
    def handle_api_error(error: APIError):
        return error.get_response()

    @app.errorhandler(HTTPException)
    def handle_http_exception(e: HTTPException):
        return APIError(message=e.description, code=e.code).get_response()

    @app.errorhandler(Exception)
    def handle_generic_exception(e: Exception):
        app.logger.error(f"Unhandled exception: {e}", exc_info=True)
        return APIError(message="An unexpected server error occurred.", code=500).get_response()
```

**`app/api/v1/services.py`**:

```python
from app.errors import NotFoundError
from app.schemas import UserCreateSchema
# Assume some ORM/DB interaction
from typing import Optional

class User: # Mock ORM model
    def __init__(self, id, name, email):
        self.id = id
        self.name = name
        self.email = email
        self.is_active = True

_users = {} # In-memory mock DB

class UserService:
    @staticmethod
    def create_user(data: UserCreateSchema) -> User:
        new_id = len(_users) + 1
        user = User(id=new_id, name=data.name, email=data.email)
        _users[new_id] = user
        return user

    @staticmethod
    def get_user(user_id: int) -> Optional[User]:
        user = _users.get(user_id)
        if not user:
            raise NotFoundError(f"User with ID {user_id} not found.")
        return user
```

## 4. Type Hints

**ALWAYS** use type hints for all functions, methods, and variables. This improves code readability, enables static analysis with tools like `mypy`, and reduces bugs.

```python
# Example in app/api/v1/resources.py
from flask_restful import Resource, Api
from typing import Dict, Any

class HealthCheck(Resource):
    def get(self) -> Dict[str, Any]:
        """Returns the API health status."""
        return {"status": "healthy", "version": "1.0.0"}

def register_v1_resources(api: Api) -> None:
    # ...
    api.add_resource(HealthCheck, '/v1/health')
```

## 5. Performance Considerations: Rate Limiting

Protect your API from abuse and ensure fair usage by implementing rate limiting.

### ✅ GOOD: `Flask-Limiter`

```python
# app/__init__.py (partial)
from flask import Flask
from flask_restful import Api
from flask_limiter import Limiter
from flask_limiter.util import get_remote_address
from config import Config

limiter = Limiter(
    key_func=get_remote_address,
    default_limits=["200 per day", "50 per hour"],
    storage_uri="memory://", # Use Redis in production
)

def create_app():
    app = Flask(__name__)
    app.config.from_object(Config)
    limiter.init_app(app) # Initialize limiter with the app

    # ... rest of app setup ...

    # Apply specific limits to resources
    from app.api.v1.resources import UserListResource
    limiter.limit("10 per minute")(UserListResource) # Apply to a specific resource

    return app
```

## 6. Common Pitfalls and Gotchas

*   **Mixing concerns**: Keep business logic out of resources. Resources handle HTTP, services handle logic.
*   **Inconsistent response formats**: Always return JSON, even for errors.
*   **Lack of API versioning**: Use `/v1/`, `/v2/` in URLs to manage changes.
*   **Ignoring HTTP status codes**: Use appropriate codes (200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error).
*   **No documentation**: Use OpenAPI/Swagger (consider Flask-RESTX for automatic generation).
*   **No testing**: Implement unit and integration tests with `pytest` and `factory-boy`.