Python API Design Best Practices¶

Core Principles¶

RESTful Design: Follow REST principles for consistent API design
Versioning: Implement proper API versioning strategies
Documentation: Provide comprehensive API documentation
Error Handling: Implement consistent error responses
Security: Build secure APIs with proper authentication and authorization

RESTful API Design¶

Resource-Based Design¶

# python/01-restful-api-design.py

"""
RESTful API design patterns and resource-based architecture
"""

from typing import List, Dict, Any, Optional, Union
from dataclasses import dataclass, asdict
from enum import Enum
import json
from datetime import datetime
from abc import ABC, abstractmethod

class HTTPMethod(Enum):
    """HTTP methods"""
    GET = "GET"
    POST = "POST"
    PUT = "PUT"
    PATCH = "PATCH"
    DELETE = "DELETE"

class HTTPStatus(Enum):
    """HTTP status codes"""
    OK = 200
    CREATED = 201
    NO_CONTENT = 204
    BAD_REQUEST = 400
    UNAUTHORIZED = 401
    FORBIDDEN = 403
    NOT_FOUND = 404
    METHOD_NOT_ALLOWED = 405
    CONFLICT = 409
    UNPROCESSABLE_ENTITY = 422
    INTERNAL_SERVER_ERROR = 500

@dataclass
class APIResponse:
    """Standard API response"""
    status_code: int
    data: Optional[Any] = None
    message: Optional[str] = None
    errors: Optional[List[str]] = None
    metadata: Optional[Dict[str, Any]] = None

    def to_dict(self) -> Dict[str, Any]:
        """Convert to dictionary"""
        response = {
            "status_code": self.status_code,
            "success": 200 <= self.status_code < 300
        }

        if self.data is not None:
            response["data"] = self.data

        if self.message:
            response["message"] = self.message

        if self.errors:
            response["errors"] = self.errors

        if self.metadata:
            response["metadata"] = self.metadata

        return response

@dataclass
class PaginationInfo:
    """Pagination information"""
    page: int
    per_page: int
    total: int
    total_pages: int
    has_next: bool
    has_prev: bool

    def to_dict(self) -> Dict[str, Any]:
        """Convert to dictionary"""
        return {
            "page": self.page,
            "per_page": self.per_page,
            "total": self.total,
            "total_pages": self.total_pages,
            "has_next": self.has_next,
            "has_prev": self.has_prev
        }

class Resource(ABC):
    """Base resource class"""

    def __init__(self, resource_id: str, created_at: datetime = None, updated_at: datetime = None):
        self.id = resource_id
        self.created_at = created_at or datetime.utcnow()
        self.updated_at = updated_at or datetime.utcnow()

    @abstractmethod
    def to_dict(self) -> Dict[str, Any]:
        """Convert resource to dictionary"""
        pass

    @classmethod
    @abstractmethod
    def from_dict(cls, data: Dict[str, Any]) -> 'Resource':
        """Create resource from dictionary"""
        pass

@dataclass
class User(Resource):
    """User resource"""
    name: str
    email: str
    is_active: bool = True

    def to_dict(self) -> Dict[str, Any]:
        """Convert user to dictionary"""
        return {
            "id": self.id,
            "name": self.name,
            "email": self.email,
            "is_active": self.is_active,
            "created_at": self.created_at.isoformat(),
            "updated_at": self.updated_at.isoformat()
        }

    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> 'User':
        """Create user from dictionary"""
        return cls(
            resource_id=data["id"],
            name=data["name"],
            email=data["email"],
            is_active=data.get("is_active", True),
            created_at=datetime.fromisoformat(data["created_at"]),
            updated_at=datetime.fromisoformat(data["updated_at"])
        )

class APIResource:
    """API resource handler"""

    def __init__(self, resource_type: str):
        self.resource_type = resource_type
        self.resources: Dict[str, Resource] = {}
        self.next_id = 1

    def create(self, data: Dict[str, Any]) -> APIResponse:
        """Create resource"""
        try:
            # Validate required fields
            if not data.get("name"):
                return APIResponse(
                    status_code=HTTPStatus.BAD_REQUEST.value,
                    errors=["Name is required"]
                )

            # Create resource
            resource_id = str(self.next_id)
            self.next_id += 1

            if self.resource_type == "user":
                resource = User(
                    resource_id=resource_id,
                    name=data["name"],
                    email=data["email"],
                    is_active=data.get("is_active", True)
                )
            else:
                raise ValueError(f"Unknown resource type: {self.resource_type}")

            self.resources[resource_id] = resource

            return APIResponse(
                status_code=HTTPStatus.CREATED.value,
                data=resource.to_dict(),
                message=f"{self.resource_type.title()} created successfully"
            )

        except Exception as e:
            return APIResponse(
                status_code=HTTPStatus.INTERNAL_SERVER_ERROR.value,
                errors=[str(e)]
            )

    def get(self, resource_id: str) -> APIResponse:
        """Get resource by ID"""
        if resource_id not in self.resources:
            return APIResponse(
                status_code=HTTPStatus.NOT_FOUND.value,
                errors=[f"{self.resource_type.title()} not found"]
            )

        resource = self.resources[resource_id]
        return APIResponse(
            status_code=HTTPStatus.OK.value,
            data=resource.to_dict()
        )

    def list(self, page: int = 1, per_page: int = 10) -> APIResponse:
        """List resources with pagination"""
        total = len(self.resources)
        total_pages = (total + per_page - 1) // per_page
        start = (page - 1) * per_page
        end = start + per_page

        resources = list(self.resources.values())[start:end]
        data = [resource.to_dict() for resource in resources]

        pagination = PaginationInfo(
            page=page,
            per_page=per_page,
            total=total,
            total_pages=total_pages,
            has_next=page < total_pages,
            has_prev=page > 1
        )

        return APIResponse(
            status_code=HTTPStatus.OK.value,
            data=data,
            metadata={"pagination": pagination.to_dict()}
        )

    def update(self, resource_id: str, data: Dict[str, Any]) -> APIResponse:
        """Update resource"""
        if resource_id not in self.resources:
            return APIResponse(
                status_code=HTTPStatus.NOT_FOUND.value,
                errors=[f"{self.resource_type.title()} not found"]
            )

        try:
            resource = self.resources[resource_id]

            # Update fields
            if "name" in data:
                resource.name = data["name"]
            if "email" in data:
                resource.email = data["email"]
            if "is_active" in data:
                resource.is_active = data["is_active"]

            resource.updated_at = datetime.utcnow()

            return APIResponse(
                status_code=HTTPStatus.OK.value,
                data=resource.to_dict(),
                message=f"{self.resource_type.title()} updated successfully"
            )

        except Exception as e:
            return APIResponse(
                status_code=HTTPStatus.INTERNAL_SERVER_ERROR.value,
                errors=[str(e)]
            )

    def delete(self, resource_id: str) -> APIResponse:
        """Delete resource"""
        if resource_id not in self.resources:
            return APIResponse(
                status_code=HTTPStatus.NOT_FOUND.value,
                errors=[f"{self.resource_type.title()} not found"]
            )

        del self.resources[resource_id]

        return APIResponse(
            status_code=HTTPStatus.NO_CONTENT.value,
            message=f"{self.resource_type.title()} deleted successfully"
        )

# Usage examples
def example_restful_api():
    """Example RESTful API usage"""
    # Create API resource
    user_api = APIResource("user")

    # Create user
    create_data = {
        "name": "John Doe",
        "email": "john@example.com",
        "is_active": True
    }
    create_response = user_api.create(create_data)
    print(f"Create response: {create_response.to_dict()}")

    # Get user
    user_id = "1"
    get_response = user_api.get(user_id)
    print(f"Get response: {get_response.to_dict()}")

    # List users
    list_response = user_api.list(page=1, per_page=10)
    print(f"List response: {list_response.to_dict()}")

    # Update user
    update_data = {"name": "Jane Doe"}
    update_response = user_api.update(user_id, update_data)
    print(f"Update response: {update_response.to_dict()}")

    # Delete user
    delete_response = user_api.delete(user_id)
    print(f"Delete response: {delete_response.to_dict()}")

API Versioning¶

# python/02-api-versioning.py

"""
API versioning strategies and implementation
"""

from typing import List, Dict, Any, Optional, Union
from dataclasses import dataclass
from enum import Enum
import re
from datetime import datetime

class APIVersion(Enum):
    """API version enumeration"""
    V1 = "v1"
    V2 = "v2"
    V3 = "v3"

@dataclass
class VersionInfo:
    """API version information"""
    version: str
    release_date: datetime
    deprecation_date: Optional[datetime] = None
    is_deprecated: bool = False
    is_sunset: bool = False
    sunset_date: Optional[datetime] = None

class APIVersionManager:
    """API version manager"""

    def __init__(self):
        self.versions: Dict[str, VersionInfo] = {}
        self.current_version = APIVersion.V1.value
        self.default_version = APIVersion.V1.value

    def register_version(self, version: str, release_date: datetime, 
                        deprecation_date: Optional[datetime] = None,
                        sunset_date: Optional[datetime] = None) -> None:
        """Register API version"""
        version_info = VersionInfo(
            version=version,
            release_date=release_date,
            deprecation_date=deprecation_date,
            is_deprecated=deprecation_date is not None,
            sunset_date=sunset_date,
            is_sunset=sunset_date is not None
        )
        self.versions[version] = version_info

    def get_version_info(self, version: str) -> Optional[VersionInfo]:
        """Get version information"""
        return self.versions.get(version)

    def is_version_supported(self, version: str) -> bool:
        """Check if version is supported"""
        version_info = self.get_version_info(version)
        if not version_info:
            return False

        return not version_info.is_sunset

    def get_supported_versions(self) -> List[str]:
        """Get list of supported versions"""
        return [
            version for version, info in self.versions.items()
            if not info.is_sunset
        ]

    def get_deprecated_versions(self) -> List[str]:
        """Get list of deprecated versions"""
        return [
            version for version, info in self.versions.items()
            if info.is_deprecated and not info.is_sunset
        ]

    def get_sunset_versions(self) -> List[str]:
        """Get list of sunset versions"""
        return [
            version for version, info in self.versions.items()
            if info.is_sunset
        ]

class VersionedAPI:
    """Versioned API implementation"""

    def __init__(self):
        self.version_manager = APIVersionManager()
        self.handlers: Dict[str, Dict[str, Any]] = {}
        self.setup_versions()

    def setup_versions(self) -> None:
        """Setup API versions"""
        # Register versions
        self.version_manager.register_version(
            "v1", 
            datetime(2023, 1, 1),
            deprecation_date=datetime(2024, 1, 1)
        )
        self.version_manager.register_version(
            "v2", 
            datetime(2023, 6, 1)
        )
        self.version_manager.register_version(
            "v3", 
            datetime(2024, 1, 1)
        )

    def register_handler(self, version: str, endpoint: str, handler: Any) -> None:
        """Register versioned handler"""
        if version not in self.handlers:
            self.handlers[version] = {}
        self.handlers[version][endpoint] = handler

    def get_handler(self, version: str, endpoint: str) -> Optional[Any]:
        """Get versioned handler"""
        if version not in self.handlers:
            return None
        return self.handlers[version].get(endpoint)

    def handle_request(self, version: str, endpoint: str, method: str, data: Dict[str, Any]) -> Dict[str, Any]:
        """Handle versioned request"""
        # Check if version is supported
        if not self.version_manager.is_version_supported(version):
            return {
                "error": "Unsupported API version",
                "supported_versions": self.version_manager.get_supported_versions()
            }

        # Get handler
        handler = self.get_handler(version, endpoint)
        if not handler:
            return {
                "error": "Endpoint not found",
                "version": version,
                "endpoint": endpoint
            }

        # Execute handler
        try:
            result = handler(method, data)
            return result
        except Exception as e:
            return {
                "error": str(e),
                "version": version,
                "endpoint": endpoint
            }

    def get_version_headers(self, version: str) -> Dict[str, str]:
        """Get version-specific headers"""
        version_info = self.version_manager.get_version_info(version)
        if not version_info:
            return {}

        headers = {
            "API-Version": version,
            "API-Release-Date": version_info.release_date.isoformat()
        }

        if version_info.is_deprecated:
            headers["API-Deprecation-Date"] = version_info.deprecation_date.isoformat()
            headers["Warning"] = f"API version {version} is deprecated"

        if version_info.is_sunset:
            headers["API-Sunset-Date"] = version_info.sunset_date.isoformat()
            headers["Warning"] = f"API version {version} is sunset"

        return headers

# Usage examples
def example_api_versioning():
    """Example API versioning usage"""
    # Create versioned API
    api = VersionedAPI()

    # Register handlers for different versions
    def v1_user_handler(method: str, data: Dict[str, Any]) -> Dict[str, Any]:
        return {"version": "v1", "method": method, "data": data}

    def v2_user_handler(method: str, data: Dict[str, Any]) -> Dict[str, Any]:
        return {"version": "v2", "method": method, "data": data, "enhanced": True}

    api.register_handler("v1", "users", v1_user_handler)
    api.register_handler("v2", "users", v2_user_handler)

    # Handle requests
    v1_response = api.handle_request("v1", "users", "GET", {})
    print(f"V1 response: {v1_response}")

    v2_response = api.handle_request("v2", "users", "GET", {})
    print(f"V2 response: {v2_response}")

    # Get version headers
    v1_headers = api.get_version_headers("v1")
    print(f"V1 headers: {v1_headers}")

    # Get supported versions
    supported = api.version_manager.get_supported_versions()
    print(f"Supported versions: {supported}")

API Documentation¶

# python/03-api-documentation.py

"""
API documentation generation and OpenAPI integration
"""

from typing import List, Dict, Any, Optional, Union
from dataclasses import dataclass, asdict
from enum import Enum
import json
from datetime import datetime

class HTTPMethod(Enum):
    """HTTP methods"""
    GET = "GET"
    POST = "POST"
    PUT = "PUT"
    PATCH = "PATCH"
    DELETE = "DELETE"

@dataclass
class APIParameter:
    """API parameter definition"""
    name: str
    type: str
    required: bool = False
    description: Optional[str] = None
    example: Optional[Any] = None
    default: Optional[Any] = None

@dataclass
class APIResponse:
    """API response definition"""
    status_code: int
    description: str
    schema: Optional[Dict[str, Any]] = None
    example: Optional[Any] = None

@dataclass
class APIEndpoint:
    """API endpoint definition"""
    path: str
    method: HTTPMethod
    summary: str
    description: str
    parameters: List[APIParameter]
    responses: List[APIResponse]
    tags: List[str]
    deprecated: bool = False

class APIDocumentation:
    """API documentation generator"""

    def __init__(self, title: str, version: str, description: str):
        self.title = title
        self.version = version
        self.description = description
        self.endpoints: List[APIEndpoint] = []
        self.tags: Dict[str, str] = {}

    def add_tag(self, name: str, description: str) -> None:
        """Add API tag"""
        self.tags[name] = description

    def add_endpoint(self, endpoint: APIEndpoint) -> None:
        """Add API endpoint"""
        self.endpoints.append(endpoint)

    def generate_openapi(self) -> Dict[str, Any]:
        """Generate OpenAPI specification"""
        openapi_spec = {
            "openapi": "3.0.0",
            "info": {
                "title": self.title,
                "version": self.version,
                "description": self.description
            },
            "servers": [
                {
                    "url": "https://api.example.com",
                    "description": "Production server"
                },
                {
                    "url": "https://staging-api.example.com",
                    "description": "Staging server"
                }
            ],
            "tags": [
                {"name": name, "description": description}
                for name, description in self.tags.items()
            ],
            "paths": {}
        }

        # Group endpoints by path
        paths = {}
        for endpoint in self.endpoints:
            if endpoint.path not in paths:
                paths[endpoint.path] = {}

            paths[endpoint.path][endpoint.method.value.lower()] = {
                "summary": endpoint.summary,
                "description": endpoint.description,
                "tags": endpoint.tags,
                "deprecated": endpoint.deprecated,
                "parameters": [
                    {
                        "name": param.name,
                        "in": "query" if param.name in ["page", "per_page", "sort"] else "path",
                        "required": param.required,
                        "description": param.description,
                        "schema": {"type": param.type},
                        "example": param.example
                    }
                    for param in endpoint.parameters
                ],
                "responses": {
                    str(response.status_code): {
                        "description": response.description,
                        "content": {
                            "application/json": {
                                "schema": response.schema or {"type": "object"},
                                "example": response.example
                            }
                        }
                    }
                    for response in endpoint.responses
                }
            }

        openapi_spec["paths"] = paths
        return openapi_spec

    def generate_markdown(self) -> str:
        """Generate Markdown documentation"""
        md_lines = [
            f"# {self.title}",
            f"**Version:** {self.version}",
            f"**Description:** {self.description}",
            "",
            "## Endpoints",
            ""
        ]

        # Group endpoints by tag
        endpoints_by_tag = {}
        for endpoint in self.endpoints:
            for tag in endpoint.tags:
                if tag not in endpoints_by_tag:
                    endpoints_by_tag[tag] = []
                endpoints_by_tag[tag].append(endpoint)

        for tag, endpoints in endpoints_by_tag.items():
            md_lines.extend([
                f"### {tag.title()}",
                ""
            ])

            for endpoint in endpoints:
                md_lines.extend([
                    f"#### {endpoint.method.value} {endpoint.path}",
                    f"**Summary:** {endpoint.summary}",
                    f"**Description:** {endpoint.description}",
                    ""
                ])

                if endpoint.parameters:
                    md_lines.extend([
                        "**Parameters:**",
                        ""
                    ])
                    for param in endpoint.parameters:
                        md_lines.extend([
                            f"- **{param.name}** ({param.type}){' - Required' if param.required else ''}",
                            f"  - {param.description}",
                            ""
                        ])

                if endpoint.responses:
                    md_lines.extend([
                        "**Responses:**",
                        ""
                    ])
                    for response in endpoint.responses:
                        md_lines.extend([
                            f"- **{response.status_code}** - {response.description}",
                            ""
                        ])

                md_lines.append("---")
                md_lines.append("")

        return "\n".join(md_lines)

# Usage examples
def example_api_documentation():
    """Example API documentation usage"""
    # Create API documentation
    doc = APIDocumentation(
        title="User Management API",
        version="1.0.0",
        description="API for managing users"
    )

    # Add tags
    doc.add_tag("users", "User management operations")
    doc.add_tag("authentication", "Authentication operations")

    # Add endpoints
    get_users_endpoint = APIEndpoint(
        path="/users",
        method=HTTPMethod.GET,
        summary="List users",
        description="Get a list of all users",
        parameters=[
            APIParameter("page", "integer", False, "Page number", 1),
            APIParameter("per_page", "integer", False, "Items per page", 10)
        ],
        responses=[
            APIResponse(200, "Success", {"type": "array", "items": {"type": "object"}}),
            APIResponse(400, "Bad Request"),
            APIResponse(500, "Internal Server Error")
        ],
        tags=["users"]
    )

    create_user_endpoint = APIEndpoint(
        path="/users",
        method=HTTPMethod.POST,
        summary="Create user",
        description="Create a new user",
        parameters=[
            APIParameter("name", "string", True, "User name"),
            APIParameter("email", "string", True, "User email")
        ],
        responses=[
            APIResponse(201, "Created", {"type": "object"}),
            APIResponse(400, "Bad Request"),
            APIResponse(422, "Validation Error")
        ],
        tags=["users"]
    )

    doc.add_endpoint(get_users_endpoint)
    doc.add_endpoint(create_user_endpoint)

    # Generate OpenAPI spec
    openapi_spec = doc.generate_openapi()
    print("OpenAPI spec:")
    print(json.dumps(openapi_spec, indent=2))

    # Generate Markdown documentation
    markdown_doc = doc.generate_markdown()
    print("\nMarkdown documentation:")
    print(markdown_doc)

Error Handling and Validation¶

API Error Handling¶

# python/04-api-error-handling.py

"""
API error handling and validation patterns
"""

from typing import List, Dict, Any, Optional, Union
from dataclasses import dataclass
from enum import Enum
import json
from datetime import datetime

class APIErrorCode(Enum):
    """API error codes"""
    VALIDATION_ERROR = "VALIDATION_ERROR"
    AUTHENTICATION_ERROR = "AUTHENTICATION_ERROR"
    AUTHORIZATION_ERROR = "AUTHORIZATION_ERROR"
    NOT_FOUND = "NOT_FOUND"
    CONFLICT = "CONFLICT"
    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
    INTERNAL_SERVER_ERROR = "INTERNAL_SERVER_ERROR"

@dataclass
class APIError:
    """API error definition"""
    code: APIErrorCode
    message: str
    details: Optional[Dict[str, Any]] = None
    field: Optional[str] = None

    def to_dict(self) -> Dict[str, Any]:
        """Convert to dictionary"""
        error_dict = {
            "code": self.code.value,
            "message": self.message
        }

        if self.details:
            error_dict["details"] = self.details

        if self.field:
            error_dict["field"] = self.field

        return error_dict

@dataclass
class APIErrorResponse:
    """API error response"""
    status_code: int
    errors: List[APIError]
    request_id: Optional[str] = None
    timestamp: datetime = None

    def __post_init__(self):
        if self.timestamp is None:
            self.timestamp = datetime.utcnow()

    def to_dict(self) -> Dict[str, Any]:
        """Convert to dictionary"""
        response = {
            "status_code": self.status_code,
            "success": False,
            "errors": [error.to_dict() for error in self.errors],
            "timestamp": self.timestamp.isoformat()
        }

        if self.request_id:
            response["request_id"] = self.request_id

        return response

class APIValidator:
    """API request validator"""

    def __init__(self):
        self.validators: Dict[str, callable] = {}
        self.setup_validators()

    def setup_validators(self) -> None:
        """Setup validators"""
        self.validators = {
            "required": self._validate_required,
            "email": self._validate_email,
            "min_length": self._validate_min_length,
            "max_length": self._validate_max_length,
            "min_value": self._validate_min_value,
            "max_value": self._validate_max_value,
            "pattern": self._validate_pattern
        }

    def validate(self, data: Dict[str, Any], rules: Dict[str, Dict[str, Any]]) -> List[APIError]:
        """Validate data against rules"""
        errors = []

        for field, field_rules in rules.items():
            value = data.get(field)

            for rule_name, rule_value in field_rules.items():
                if rule_name in self.validators:
                    error = self.validators[rule_name](field, value, rule_value)
                    if error:
                        errors.append(error)

        return errors

    def _validate_required(self, field: str, value: Any, required: bool) -> Optional[APIError]:
        """Validate required field"""
        if required and (value is None or value == ""):
            return APIError(
                code=APIErrorCode.VALIDATION_ERROR,
                message=f"Field '{field}' is required",
                field=field
            )
        return None

    def _validate_email(self, field: str, value: Any, is_email: bool) -> Optional[APIError]:
        """Validate email format"""
        if is_email and value and "@" not in str(value):
            return APIError(
                code=APIErrorCode.VALIDATION_ERROR,
                message=f"Field '{field}' must be a valid email",
                field=field
            )
        return None

    def _validate_min_length(self, field: str, value: Any, min_length: int) -> Optional[APIError]:
        """Validate minimum length"""
        if value and len(str(value)) < min_length:
            return APIError(
                code=APIErrorCode.VALIDATION_ERROR,
                message=f"Field '{field}' must be at least {min_length} characters",
                field=field
            )
        return None

    def _validate_max_length(self, field: str, value: Any, max_length: int) -> Optional[APIError]:
        """Validate maximum length"""
        if value and len(str(value)) > max_length:
            return APIError(
                code=APIErrorCode.VALIDATION_ERROR,
                message=f"Field '{field}' must be at most {max_length} characters",
                field=field
            )
        return None

    def _validate_min_value(self, field: str, value: Any, min_value: Union[int, float]) -> Optional[APIError]:
        """Validate minimum value"""
        if value is not None and value < min_value:
            return APIError(
                code=APIErrorCode.VALIDATION_ERROR,
                message=f"Field '{field}' must be at least {min_value}",
                field=field
            )
        return None

    def _validate_max_value(self, field: str, value: Any, max_value: Union[int, float]) -> Optional[APIError]:
        """Validate maximum value"""
        if value is not None and value > max_value:
            return APIError(
                code=APIErrorCode.VALIDATION_ERROR,
                message=f"Field '{field}' must be at most {max_value}",
                field=field
            )
        return None

    def _validate_pattern(self, field: str, value: Any, pattern: str) -> Optional[APIError]:
        """Validate pattern"""
        if value and not re.match(pattern, str(value)):
            return APIError(
                code=APIErrorCode.VALIDATION_ERROR,
                message=f"Field '{field}' does not match required pattern",
                field=field
            )
        return None

class APIErrorHandler:
    """API error handler"""

    def __init__(self):
        self.validator = APIValidator()

    def handle_validation_error(self, errors: List[APIError]) -> APIErrorResponse:
        """Handle validation errors"""
        return APIErrorResponse(
            status_code=400,
            errors=errors
        )

    def handle_authentication_error(self, message: str = "Authentication required") -> APIErrorResponse:
        """Handle authentication errors"""
        return APIErrorResponse(
            status_code=401,
            errors=[APIError(
                code=APIErrorCode.AUTHENTICATION_ERROR,
                message=message
            )]
        )

    def handle_authorization_error(self, message: str = "Insufficient permissions") -> APIErrorResponse:
        """Handle authorization errors"""
        return APIErrorResponse(
            status_code=403,
            errors=[APIError(
                code=APIErrorCode.AUTHORIZATION_ERROR,
                message=message
            )]
        )

    def handle_not_found_error(self, resource: str = "Resource") -> APIErrorResponse:
        """Handle not found errors"""
        return APIErrorResponse(
            status_code=404,
            errors=[APIError(
                code=APIErrorCode.NOT_FOUND,
                message=f"{resource} not found"
            )]
        )

    def handle_conflict_error(self, message: str = "Resource conflict") -> APIErrorResponse:
        """Handle conflict errors"""
        return APIErrorResponse(
            status_code=409,
            errors=[APIError(
                code=APIErrorCode.CONFLICT,
                message=message
            )]
        )

    def handle_internal_error(self, message: str = "Internal server error") -> APIErrorResponse:
        """Handle internal errors"""
        return APIErrorResponse(
            status_code=500,
            errors=[APIError(
                code=APIErrorCode.INTERNAL_SERVER_ERROR,
                message=message
            )]
        )

# Usage examples
def example_api_error_handling():
    """Example API error handling usage"""
    # Create error handler
    error_handler = APIErrorHandler()

    # Create validator
    validator = APIValidator()

    # Validate data
    data = {"name": "", "email": "invalid-email"}
    rules = {
        "name": {"required": True, "min_length": 2},
        "email": {"required": True, "email": True}
    }

    errors = validator.validate(data, rules)
    if errors:
        error_response = error_handler.handle_validation_error(errors)
        print(f"Validation error: {error_response.to_dict()}")

    # Handle different error types
    auth_error = error_handler.handle_authentication_error()
    print(f"Auth error: {auth_error.to_dict()}")

    not_found_error = error_handler.handle_not_found_error("User")
    print(f"Not found error: {not_found_error.to_dict()}")

TL;DR Runbook¶

Quick Start¶

# 1. Basic API response
response = APIResponse(
    status_code=200,
    data={"id": 1, "name": "John"},
    message="Success"
)

# 2. API versioning
version_manager = APIVersionManager()
version_manager.register_version("v1", datetime(2023, 1, 1))

# 3. API documentation
doc = APIDocumentation("My API", "1.0.0", "API description")
doc.add_endpoint(endpoint)

# 4. Error handling
error_handler = APIErrorHandler()
validation_error = error_handler.handle_validation_error(errors)

# 5. Request validation
validator = APIValidator()
errors = validator.validate(data, rules)

Essential Patterns¶

# Complete API design setup
def setup_api_design():
    """Setup complete API design environment"""

    # API resource
    api_resource = APIResource("users")

    # Version manager
    version_manager = APIVersionManager()

    # Documentation
    doc = APIDocumentation("User API", "1.0.0", "User management API")

    # Error handler
    error_handler = APIErrorHandler()

    # Validator
    validator = APIValidator()

    print("API design setup complete!")