API Development Requirements

AWX REST API Best Practices

Version:: 1.0
Date:: September 2025
Based on:: AWX Enterprise Django REST Framework Analysis
Generated by:: Claude Code AI

Important

This document defines mandatory API development standards for enterprise-grade Django REST Framework applications based on AWX production patterns.

1. API Architecture and Configuration 

1.1 Django REST Framework Configuration 

REQUIRED: Comprehensive DRF setup with enterprise-grade defaults:

# settings/defaults.py
REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'awx.api.pagination.Pagination',
    'PAGE_SIZE': 25,
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'awx.api.authentication.JWTAuthentication',
        'awx.api.authentication.SessionAuthentication',
        'awx.api.authentication.LoggedBasicAuthentication',
    ),
    'DEFAULT_PERMISSION_CLASSES': (
        'awx.api.permissions.ModelAccessPermission',
    ),
    'DEFAULT_PARSER_CLASSES': (
        'awx.api.parsers.JSONParser',
    ),
    'DEFAULT_RENDERER_CLASSES': (
        'awx.api.renderers.DefaultJSONRenderer',
        'awx.api.renderers.BrowsableAPIRenderer',
    ),
    'DEFAULT_METADATA_CLASS': 'awx.api.metadata.Metadata',
    'EXCEPTION_HANDLER': 'awx.api.views.api_exception_handler',
    'VIEW_DESCRIPTION_FUNCTION': 'awx.api.generics.get_view_description',
    'NON_FIELD_ERRORS_KEY': '__all__',
    'DEFAULT_VERSION': 'v2',
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema',
}

Configuration Requirements:

Centralized Settings: API configuration must be centralized and environment-aware
Version Control: Default API version must be explicitly configured
Error Handling: Custom exception handler for consistent error responses

1.2 Modular API Structure 

REQUIRED: Organize API with clear separation of concerns:

api/
├── __init__.py
├── authentication.py       # Custom authentication classes
├── permissions.py          # Permission and access control
├── serializers.py          # Base serializer patterns
├── generics.py            # Custom view classes
├── pagination.py          # Pagination strategies
├── renderers.py           # Response formatters
├── fields.py              # Custom field types
├── exceptions.py          # Custom exception classes
├── metadata.py            # Field metadata for clients
├── urls/                  # Resource-specific URL modules
│   ├── __init__.py
│   ├── organization.py
│   ├── user.py
│   ├── project.py
│   └── job_template.py
└── views/                 # Resource-specific view modules
    ├── __init__.py
    ├── organization.py
    └── user.py

Structural Requirements:

Resource-Based Organization: Each API resource must have its own module
URL Separation: URL patterns organized by resource type
View Inheritance: Consistent view hierarchy with shared base classes
Component Isolation: Authentication, permissions, and serialization in separate modules

2. REST API Design Standards 

2.1 Core REST Principles 

MANDATORY: All APIs must adhere to these fundamental principles:

REST Design Requirements
Principle	Implementation Requirement
Paginate Everything	Any endpoint returning collections MUST be paginated
Performance Target	Expected response time ≤ 250ms (1/4 second)
RBAC Filtering	All collections MUST be filtered by user access permissions
API Discoverability	All endpoints MUST be traversable from API root ‘/’
RESTful Verbs	HTTP methods MUST follow REST conventions
Constant Time Queries	Database queries MUST NOT vary with result set size

2.2 URL Pattern Standards 

REQUIRED: Consistent RESTful URL patterns:

# Standard resource patterns
urlpatterns = [
    # Collection endpoints
    re_path(r'^$', ResourceList.as_view(), name='resource_list'),

    # Instance endpoints
    re_path(r'^(?P<pk>[0-9]+)/$', ResourceDetail.as_view(), name='resource_detail'),

    # Nested resource relationships
    re_path(r'^(?P<pk>[0-9]+)/children/$', ResourceChildrenList.as_view(),
            name='resource_children_list'),

    # Action endpoints
    re_path(r'^(?P<pk>[0-9]+)/launch/$', ResourceLaunch.as_view(),
            name='resource_launch'),
    re_path(r'^(?P<pk>[0-9]+)/copy/$', ResourceCopy.as_view(),
            name='resource_copy'),
    re_path(r'^(?P<pk>[0-9]+)/callback/$', ResourceCallback.as_view(),
            name='resource_callback'),
]

URL Requirements:

Numeric Primary Keys: Use (?P<pk>[0-9]+) pattern for resource IDs
Hierarchical Relationships: Support nested resource access patterns
Action Endpoints: Additional endpoints for resource-specific actions
Consistent Naming: Follow resource_action naming convention

2.3 HTTP Method Standards 

REQUIRED: Proper HTTP method usage:

HTTP Method Requirements
Method	Usage	Requirements
GET	Retrieve resources	Idempotent, no side effects, cacheable
POST	Create resources	Returns 201 Created with Location header
PUT	Update/Replace resources	Idempotent, full resource replacement
PATCH	Partial updates	Non-idempotent, partial resource modification
DELETE	Remove resources	Idempotent, returns 204 No Content
OPTIONS	Metadata discovery	Returns available methods and field metadata

3. Authentication and Authorization 

3.1 Multi-Layer Authentication Stack 

REQUIRED: Implement comprehensive authentication system:

# api/authentication.py
class LoggedBasicAuthentication(authentication.BasicAuthentication):
    """Basic authentication with comprehensive logging"""

    def authenticate(self, request):
        if not settings.AUTH_BASIC_ENABLED:
            return

        ret = super().authenticate(request)
        if ret:
            username = ret[0].username if ret[0] else '<none>'
            logger.info(
                f"User {username} performed {request.method} "
                f"to {request.path} through the API using Basic Auth"
            )
        return ret

class SessionAuthentication(authentication.SessionAuthentication):
    """Enhanced session authentication with CSRF handling"""

    def authenticate(self, request):
        # Custom session validation logic
        return super().authenticate(request)

Authentication Requirements:

JWT Authentication: Primary token-based authentication
Session Authentication: Browser-based session support
Basic Authentication: With comprehensive request logging
Authentication Logging: All authentication events must be logged
Fallback Support: Multiple authentication methods for different clients

3.2 Role-Based Access Control (RBAC)

REQUIRED: Implement comprehensive permission system:

# api/permissions.py
class ModelAccessPermission(permissions.BasePermission):
    """Advanced model-based access control"""

    def has_permission(self, request, view):
        # Check view-level permissions
        if not hasattr(view, 'model'):
            return False

        # Parent resource permission checking
        if hasattr(view, 'parent_model'):
            parent_obj = view.get_parent_object()
            if not check_user_access(
                request.user,
                view.parent_model,
                'read',
                parent_obj
            ):
                return False

        return True

    def has_object_permission(self, request, view, obj):
        # Object-level permission checking
        permission_map = {
            'GET': 'read',
            'POST': 'add',
            'PUT': 'change',
            'PATCH': 'change',
            'DELETE': 'delete',
        }

        required_permission = permission_map.get(request.method, 'read')
        return check_user_access(request.user, view.model, required_permission, obj)

RBAC Requirements:

Method-Specific Permissions: Different permissions for GET, POST, PUT, DELETE
Object-Level Control: Fine-grained access control on individual resources
Hierarchical Permissions: Parent-child relationship permission inheritance
Data-Aware Permissions: Access control based on request data content
Audit Trail: All permission checks must be logged

3.3 API Token Management 

REQUIRED: Secure token handling patterns:

# Token-based authentication requirements
JWT_SETTINGS = {
    'ACCESS_TOKEN_LIFETIME': timedelta(hours=1),
    'REFRESH_TOKEN_LIFETIME': timedelta(days=7),
    'ROTATE_REFRESH_TOKENS': True,
    'BLACKLIST_AFTER_ROTATION': True,
    'ALGORITHM': 'RS256',
    'SIGNING_KEY': settings.JWT_PRIVATE_KEY,
    'VERIFYING_KEY': settings.JWT_PUBLIC_KEY,
}

Token Requirements:

Short-Lived Access Tokens: Maximum 1-hour expiration
Refresh Token Rotation: Automatic rotation on refresh
Token Blacklisting: Revoked tokens must be blacklisted
Asymmetric Encryption: Use RS256 with key pairs
Secure Storage: Private keys must be externally managed

4. Serialization and Data Validation 

4.1 Base Serializer Architecture 

REQUIRED: Implement consistent serializer patterns:

# api/serializers.py
class BaseSerializer(serializers.ModelSerializer, metaclass=BaseSerializerMetaclass):
    """Base serializer with common enterprise patterns"""

    class Meta:
        fields = (
            'id', 'type', 'url', 'related', 'summary_fields',
            'created', 'modified', 'name', 'description'
        )
        summary_fields = ()
        summarizable_fields = ()

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self._setup_summary_fields()
        self._setup_related_fields()

    def _setup_summary_fields(self):
        """Configure optimized nested data representation"""
        pass

    def _setup_related_fields(self):
        """Configure related resource URL fields"""
        pass

Serializer Requirements:

Base Class Inheritance: All serializers must inherit from base serializer
Common Fields: Standardized fields across all resources
Summary Fields: Optimized nested data representation
Related URLs: Structured related resource references
Metaclass Usage: Custom metaclass for field inheritance

4.2 Custom Field Types 

REQUIRED: Domain-specific field validation:

# api/fields.py
class BooleanNullField(NullFieldMixin, serializers.BooleanField):
    """Boolean field that allows null and empty string as False"""

    def to_internal_value(self, data):
        if data is None or data == '':
            return False
        return super().to_internal_value(data)

class CharNullField(NullFieldMixin, serializers.CharField):
    """Char field that allows null input and coerces to empty string"""

    def to_internal_value(self, data):
        if data is None:
            return ''
        return super().to_internal_value(data)

class JSONField(serializers.Field):
    """Custom JSON field with validation"""

    def to_representation(self, value):
        return json.loads(value) if isinstance(value, str) else value

    def to_internal_value(self, data):
        try:
            return json.dumps(data)
        except (TypeError, ValueError):
            raise serializers.ValidationError("Invalid JSON data")

Field Requirements:

Null Handling: Consistent null value processing across field types
Type Coercion: Automatic data type conversion where appropriate
Validation Mixins: Reusable validation logic through mixins
Custom Serialization: Domain-specific serialization logic

4.3 Data Validation Patterns 

REQUIRED: Comprehensive validation strategies:

class ResourceSerializer(BaseSerializer):
    """Example resource serializer with validation"""

    class Meta(BaseSerializer.Meta):
        model = Resource
        fields = BaseSerializer.Meta.fields + ('status', 'type', 'configuration')

    def validate_configuration(self, value):
        """Field-level validation"""
        if not isinstance(value, dict):
            raise serializers.ValidationError("Configuration must be a JSON object")
        return value

    def validate(self, data):
        """Object-level validation"""
        if data.get('status') == 'active' and not data.get('configuration'):
            raise serializers.ValidationError(
                "Active resources must have configuration"
            )
        return data

    def create(self, validated_data):
        """Custom creation logic with audit trail"""
        instance = super().create(validated_data)
        self._log_creation(instance)
        return instance

Validation Requirements:

Field-Level Validation: Validate individual fields with custom logic
Object-Level Validation: Cross-field validation rules
Business Logic Validation: Domain-specific validation rules
Audit Logging: All validation failures must be logged
Error Formatting: Consistent error message structure

5. Performance and Optimization 

5.1 Query Optimization Standards 

MANDATORY: Database query performance requirements:

Warning

Critical Performance Rule: The number of database queries MUST be constant time and MUST NOT vary with the size of the result set.

# api/generics.py
def optimize_queryset(queryset, view, remove_django_content_type=False):
    """Query optimization for API views"""

    # Select related for foreign keys
    if hasattr(view, 'select_related_fields'):
        queryset = queryset.select_related(*view.select_related_fields)

    # Prefetch related for many-to-many and reverse foreign keys
    if hasattr(view, 'prefetch_related_fields'):
        queryset = queryset.prefetch_related(*view.prefetch_related_fields)

    # Only select necessary fields
    if hasattr(view, 'only_fields'):
        queryset = queryset.only(*view.only_fields)

    return queryset

Query Optimization Requirements:

Constant Time Queries: Query count independent of result set size
Select Related: Use select_related() for foreign key relationships
Prefetch Related: Use prefetch_related() for many-to-many relationships
Field Selection: Use only() to limit selected fields
No Serializer Queries: Database queries prohibited in serializers

5.2 Pagination Strategy 

REQUIRED: Advanced pagination with performance optimization:

# api/pagination.py
class Pagination(pagination.PageNumberPagination):
    """Enterprise pagination with performance features"""

    page_size_query_param = 'page_size'
    max_page_size = 200
    count_disabled = False

    def paginate_queryset(self, queryset, request, **kwargs):
        # Optional count disabling for large datasets
        self.count_disabled = 'count_disabled' in request.query_params

        if self.count_disabled:
            # Skip expensive COUNT query for large datasets
            return self._paginate_without_count(queryset, request)

        return super().paginate_queryset(queryset, request, **kwargs)

    def get_paginated_response(self, data):
        response_data = {
            'count': self.page.paginator.count if not self.count_disabled else None,
            'next': self.get_next_link(),
            'previous': self.get_previous_link(),
            'results': data
        }
        return Response(response_data)

Pagination Requirements:

Performance Optimization: Optional count disabling for large datasets
Configurable Page Sizes: Maximum page size limits with user control
Consistent Format: Standardized pagination response format
Memory Efficiency: Efficient memory usage for large result sets

5.3 Caching Strategies 

REQUIRED: Multi-level caching implementation:

# api/middleware.py
class SettingsCacheMiddleware(MiddlewareMixin):
    """Clear settings cache on each request"""

    def process_request(self, request):
        from django.conf import settings
        if hasattr(settings, '_awx_conf_memoizedcache'):
            settings._awx_conf_memoizedcache.clear()

class ResponseCacheMiddleware(MiddlewareMixin):
    """Cache API responses based on content type"""

    def process_response(self, request, response):
        # Cache responses for GET requests only
        if request.method == 'GET' and response.status_code == 200:
            cache_key = self._generate_cache_key(request)
            cache.set(cache_key, response.content, timeout=300)
        return response

Caching Requirements:

Settings Caching: Intelligent configuration caching with invalidation
Response Caching: Cache GET responses with appropriate TTL
Cache Invalidation: Automatic cache clearing on data changes
Selective Caching: Cache only appropriate endpoints and data

6. Error Handling and Status Codes 

6.1 Custom Exception Hierarchy 

REQUIRED: Comprehensive exception handling system:

# api/exceptions.py
class APIException(Exception):
    """Base API exception with structured error format"""
    status_code = 400
    detail = "An error occurred"

    def __init__(self, detail=None, code=None):
        if detail is not None:
            self.detail = detail
        if code is not None:
            self.status_code = code

class ActiveJobConflict(ValidationError):
    """Resource conflict with active jobs"""
    status_code = 409

    def __init__(self, active_jobs):
        super().__init__()
        self.detail = {
            "error": "Resource is being used by running jobs",
            "active_jobs": active_jobs,
            "conflict_type": "active_job_dependency"
        }

class PermissionDenied(APIException):
    """Enhanced permission denied with context"""
    status_code = 403

    def __init__(self, detail=None, required_permission=None, resource=None):
        super().__init__(detail)
        self.detail = {
            "error": detail or "Permission denied",
            "required_permission": required_permission,
            "resource": resource
        }

Exception Requirements:

Structured Error Format: Consistent error response structure
HTTP Status Codes: Proper status code mapping for different error types
Context Information: Rich error context for debugging and user feedback
Exception Hierarchy: Logical exception inheritance structure

6.2 Global Exception Handler 

REQUIRED: Centralized exception processing:

# api/views/__init__.py
def api_exception_handler(exc, context):
    """Enhanced exception handler with logging and standardization"""

    # Handle database integrity errors
    if isinstance(exc, IntegrityError):
        exc = ParseError("Database constraint violation: " + str(exc))

    # Handle Django field errors
    if isinstance(exc, FieldError):
        exc = ParseError("Invalid field specification: " + str(exc))

    # Handle permission errors with context
    if isinstance(exc, PermissionDenied):
        logger.warning(
            f"Permission denied for user {context['request'].user} "
            f"accessing {context['request'].path}"
        )

    # Use default DRF exception handler
    response = exception_handler(exc, context)

    # Add custom error metadata
    if response is not None:
        response.data['timestamp'] = timezone.now().isoformat()
        response.data['path'] = context['request'].path
        response.data['method'] = context['request'].method

    return response

Exception Handler Requirements:

Comprehensive Logging: All exceptions must be logged with context
Error Transformation: Convert database/system errors to API errors
Metadata Addition: Include request context in error responses
Security Considerations: Sanitize error messages for production

6.3 Status Code Standards 

REQUIRED: Proper HTTP status code usage:

Status Code Requirements
Code	Usage	Implementation Requirements
200 OK	Successful GET, PUT, PATCH	Include response timing headers
201 Created	Successful POST	Include Location header with new resource URL
204 No Content	Successful DELETE	No response body required
400 Bad Request	Validation errors	Include detailed field-level error information
401 Unauthorized	Authentication required	Include WWW-Authenticate header
403 Forbidden	Permission denied	Include required permission information
404 Not Found	Resource not found	Include suggested alternatives if available
409 Conflict	Resource conflicts	Include conflict resolution information
422 Unprocessable Entity	Business logic errors	Include business rule violation details
500 Internal Server Error	System errors	Log full error details, return sanitized message

7. API Documentation and Discovery 

7.1 OpenAPI/Swagger Integration 

REQUIRED: Comprehensive API documentation system:

# api/swagger.py
class CustomSwaggerAutoSchema(SwaggerAutoSchema):
    """Enhanced Swagger schema generation"""

    def get_tags(self, operation_keys=None):
        """Generate logical API tags"""
        tags = []

        if hasattr(self.view, 'swagger_topic'):
            tags.append(str(self.view.swagger_topic).title())
        elif hasattr(self.view, 'serializer_class'):
            serializer = self.view.serializer_class
            if hasattr(serializer, 'Meta') and hasattr(serializer.Meta, 'model'):
                model_name = serializer.Meta.model._meta.verbose_name_plural
                tags.append(str(model_name).title())

        return tags

    def get_operation_id(self, operation_keys):
        """Generate unique operation IDs"""
        return '_'.join(operation_keys)

    def get_description(self):
        """Enhanced operation descriptions"""
        description = super().get_description()

        # Add permission requirements
        if hasattr(self.view, 'required_permissions'):
            description += f"\n\nRequired permissions: {self.view.required_permissions}"

        # Add rate limiting information
        if hasattr(self.view, 'throttle_classes'):
            description += f"\n\nRate limiting: Applied"

        return description

Documentation Requirements:

Auto-Generated Schemas: Complete OpenAPI 3.0 schema generation
Logical Grouping: API endpoints grouped by resource/functionality
Operation Metadata: Detailed operation descriptions with examples
Permission Documentation: Clear permission requirements for each endpoint
Response Examples: Example responses for all status codes

7.2 Rich Field Metadata 

REQUIRED: Comprehensive field information for clients:

# api/metadata.py
class Metadata(metadata.SimpleMetadata):
    """Enhanced metadata with comprehensive field information"""

    def get_field_info(self, field):
        """Generate detailed field metadata"""
        field_info = super().get_field_info(field)

        # Add validation information
        field_info['validators'] = self._get_validator_info(field)

        # Add filtering capabilities
        field_info['filterable'] = getattr(field, 'filterable', False)
        field_info['searchable'] = getattr(field, 'searchable', False)

        # Add help text and examples
        field_info['help_text'] = getattr(field, 'help_text', None)
        field_info['example'] = getattr(field, 'example', None)

        # Add relationship information
        if hasattr(field, 'queryset'):
            field_info['related_model'] = field.queryset.model.__name__
            field_info['related_url'] = self._get_related_url(field)

        return field_info

    def _get_validator_info(self, field):
        """Extract validator information"""
        validators = []
        for validator in field.validators:
            validators.append({
                'type': validator.__class__.__name__,
                'message': getattr(validator, 'message', None)
            })
        return validators

Metadata Requirements:

Validation Rules: Complete field validation information
Filtering Support: Indicate which fields support filtering/searching
Relationship Data: Information about related resources
Help Text: User-friendly field descriptions and examples
Client Tooling: Metadata suitable for auto-generating client SDKs

7.3 API Discoverability 

REQUIRED: Complete API traversal from root endpoint:

# api/views/root.py
class ApiRootView(APIView):
    """API root with complete endpoint discovery"""

    def get(self, request, format=None):
        """Return all available API endpoints"""
        endpoints = {
            'ping': reverse('api:ping', request=request),
            'config': reverse('api:config', request=request),
            'me': reverse('api:me', request=request),
            'dashboard': reverse('api:dashboard', request=request),
            'organizations': reverse('api:organization_list', request=request),
            'users': reverse('api:user_list', request=request),
            'teams': reverse('api:team_list', request=request),
            'projects': reverse('api:project_list', request=request),
            'inventories': reverse('api:inventory_list', request=request),
            'job_templates': reverse('api:job_template_list', request=request),
            'jobs': reverse('api:job_list', request=request),
        }

        # Add versioning information
        endpoints['current_version'] = request.version
        endpoints['available_versions'] = ['v1', 'v2']

        # Add authentication information
        endpoints['auth_methods'] = [
            'jwt', 'session', 'basic'
        ]

        return Response(endpoints)

Discoverability Requirements:

Complete Traversal: All endpoints accessible from API root
Version Information: Available API versions clearly indicated
Authentication Methods: Supported authentication mechanisms listed
Relationship Links: Related resource URLs in all responses

8. API Versioning Strategy 

8.1 URL Path Versioning 

REQUIRED: Clean URL-based versioning system:

# api/versioning.py
class URLPathVersioning(BaseVersioning):
    """URL path-based API versioning"""

    version_param = 'version'
    default_version = 'v2'
    allowed_versions = ['v1', 'v2']

    def determine_version(self, request, *args, **kwargs):
        version = kwargs.get(self.version_param, self.default_version)
        if version not in self.allowed_versions:
            raise exceptions.NotFound(f"API version '{version}' not found")
        return version

    def reverse(self, viewname, args=None, kwargs=None, request=None, format=None, **extra):
        if request.version is not None:
            kwargs = {} if kwargs is None else kwargs
            kwargs[self.version_param] = request.version
        return super().reverse(viewname, args, kwargs, request, format, **extra)

Versioning Requirements:

URL Path Format: Use /api/v{version}/ format
Backward Compatibility: Support multiple API versions simultaneously
Default Version: Explicit default version configuration
Version Discovery: Available versions discoverable from API root
Graceful Deprecation: Clear deprecation timeline for old versions

8.2 Version-Specific Behavior 

REQUIRED: Handle version differences in views and serializers:

# api/views/versioned.py
class VersionedViewMixin:
    """Mixin for version-aware view behavior"""

    def get_serializer_class(self):
        """Return version-specific serializer"""
        base_serializer = super().get_serializer_class()

        if self.request.version == 'v1':
            # Use legacy serializer for v1
            return getattr(self, 'v1_serializer_class', base_serializer)
        elif self.request.version == 'v2':
            # Use current serializer for v2
            return base_serializer

        return base_serializer

    def get_queryset(self):
        """Return version-specific queryset"""
        queryset = super().get_queryset()

        # Apply version-specific filtering
        if self.request.version == 'v1':
            # Legacy filtering logic
            queryset = self._apply_v1_filters(queryset)

        return queryset

Version Management Requirements:

Serializer Versioning: Version-specific serializer classes
Behavior Versioning: Different view behavior for different versions
Data Migration: Automatic data format conversion between versions
Feature Flags: Version-specific feature availability

9. Testing Requirements 

9.1 Comprehensive Test Coverage 

MANDATORY: Complete API test coverage requirements:

Important

Critical Testing Rule: Every API URL/endpoint MUST have unit test coverage with both positive and negative test cases.

# tests/api/test_resource.py
class TestResourceAPI:
    """Comprehensive API testing for Resource endpoints"""

    def test_list_resources_success(self, api_client, user):
        """Test successful resource listing"""
        # Setup test data
        resources = ResourceFactory.create_batch(3)

        # Make request
        response = api_client.get('/api/v2/resources/')

        # Assertions
        assert response.status_code == 200
        assert response.data['count'] == 3
        assert len(response.data['results']) == 3

    def test_list_resources_permission_denied(self, api_client, user_without_permissions):
        """Test resource listing without permissions"""
        ResourceFactory.create_batch(3)

        api_client.force_authenticate(user=user_without_permissions)
        response = api_client.get('/api/v2/resources/')

        assert response.status_code == 403
        assert 'permission' in response.data['error'].lower()

    def test_create_resource_success(self, api_client, user):
        """Test successful resource creation"""
        data = {
            'name': 'Test Resource',
            'description': 'Test Description',
            'configuration': {'key': 'value'}
        }

        response = api_client.post('/api/v2/resources/', data)

        assert response.status_code == 201
        assert response.data['name'] == data['name']
        assert 'id' in response.data

    @pytest.mark.parametrize('invalid_data,expected_error', [
        ({'name': ''}, 'name'),
        ({'name': 'test'}, 'description'),
        ({'name': 'test', 'description': 'test', 'configuration': 'invalid'}, 'configuration'),
    ])
    def test_create_resource_validation_errors(self, api_client, user, invalid_data, expected_error):
        """Test resource creation validation"""
        response = api_client.post('/api/v2/resources/', invalid_data)

        assert response.status_code == 400
        assert expected_error in response.data

Testing Requirements:

Positive Test Cases: Test all successful operation scenarios
Negative Test Cases: Test all error conditions and edge cases
Permission Testing: Test access control for all user types
Validation Testing: Test all field validation rules
Parameterized Testing: Use data-driven test approaches
Factory Pattern: Use factories for test data generation

9.2 Performance Testing 

REQUIRED: API performance validation:

# tests/api/test_performance.py
class TestAPIPerformance:
    """Performance testing for API endpoints"""

    def test_query_count_constant(self, api_client, django_assert_num_queries):
        """Ensure query count doesn't vary with result set size"""

        # Test with small dataset
        ResourceFactory.create_batch(10)
        with django_assert_num_queries(5):  # Expected query count
            response = api_client.get('/api/v2/resources/')
            assert response.status_code == 200

        # Test with larger dataset - query count should remain same
        ResourceFactory.create_batch(90)  # Total 100 resources
        with django_assert_num_queries(5):  # Same query count
            response = api_client.get('/api/v2/resources/')
            assert response.status_code == 200

    def test_response_time_target(self, api_client):
        """Ensure response time meets performance targets"""
        import time

        start_time = time.time()
        response = api_client.get('/api/v2/resources/')
        end_time = time.time()

        response_time = end_time - start_time
        assert response_time < 0.25  # 250ms target
        assert response.status_code == 200

Performance Test Requirements:

Query Count Testing: Verify constant-time database queries
Response Time Testing: Validate performance targets (≤250ms)
Load Testing: Test with realistic data volumes
Memory Usage: Monitor memory consumption patterns

10. Security Requirements 

10.1 Authentication Security 

REQUIRED: Secure authentication implementation:

# Security configuration
AUTHENTICATION_SECURITY = {
    'PASSWORD_RESET_TIMEOUT': 3600,  # 1 hour
    'LOGIN_ATTEMPT_LIMIT': 5,
    'LOGIN_LOCKOUT_DURATION': 300,   # 5 minutes
    'JWT_ACCESS_TOKEN_LIFETIME': 3600,  # 1 hour
    'JWT_REFRESH_TOKEN_LIFETIME': 604800,  # 7 days
    'SESSION_COOKIE_AGE': 1800,      # 30 minutes
    'CSRF_COOKIE_HTTPONLY': True,
    'SESSION_COOKIE_SECURE': True,
    'SESSION_COOKIE_SAMESITE': 'Lax',
}

Authentication Security Requirements:

Rate Limiting: Implement login attempt limiting
Token Expiration: Short-lived access tokens with refresh mechanism
Secure Cookies: HTTPOnly, Secure, and SameSite cookie attributes
Brute Force Protection: Account lockout after failed attempts
Session Management: Configurable session timeouts

10.2 Authorization Security 

REQUIRED: Comprehensive access control:

# api/permissions.py
class SecureModelAccessPermission(permissions.BasePermission):
    """Security-enhanced permission checking"""

    def has_permission(self, request, view):
        # Log all permission checks for security audit
        logger.info(
            f"Permission check: {request.user} accessing "
            f"{view.__class__.__name__} via {request.method}"
        )

        # Check user account status
        if not request.user.is_active:
            logger.warning(f"Inactive user {request.user} attempted access")
            return False

        # Check IP whitelist if configured
        if hasattr(settings, 'API_IP_WHITELIST'):
            client_ip = self._get_client_ip(request)
            if client_ip not in settings.API_IP_WHITELIST:
                logger.warning(f"Access denied from IP {client_ip}")
                return False

        return super().has_permission(request, view)

Authorization Security Requirements:

Audit Logging: Log all access attempts and permission checks
Account Status Checking: Verify user account is active
IP Whitelisting: Optional IP-based access control
Principle of Least Privilege: Minimal required permissions only
Session Validation: Verify session integrity on each request

10.3 Data Protection 

REQUIRED: Secure data handling:

# api/serializers.py
class SecureSerializer(BaseSerializer):
    """Security-enhanced serializer"""

    sensitive_fields = ['password', 'secret_key', 'private_key', 'token']

    def to_representation(self, instance):
        """Remove sensitive data from responses"""
        data = super().to_representation(instance)

        # Mask sensitive fields
        for field in self.sensitive_fields:
            if field in data:
                data[field] = '***REDACTED***'

        return data

    def validate(self, attrs):
        """Enhanced validation with security checks"""
        attrs = super().validate(attrs)

        # Validate against known security patterns
        for field, value in attrs.items():
            if self._contains_injection_attempt(value):
                logger.warning(f"Potential injection attempt in field {field}")
                raise serializers.ValidationError(f"Invalid value for {field}")

        return attrs

Data Protection Requirements:

Sensitive Data Masking: Automatic masking of sensitive fields in responses
Input Sanitization: Validate and sanitize all input data
Injection Prevention: Protect against SQL injection and XSS attacks
Data Encryption: Encrypt sensitive data at rest and in transit
Audit Trail: Log all data access and modification events

Compliance Checklist 

API Design Standards 

Requirement	Status
RESTful URL patterns implemented	☐
Proper HTTP method usage	☐
Consistent error responses	☐
Comprehensive pagination	☐
API versioning strategy	☐
OpenAPI documentation	☐
API discoverability from root	☐
Performance targets met (≤250ms)	☐

Security Requirements 

Requirement	Status
Multi-factor authentication	☐
RBAC implementation	☐
Secure token management	☐
Input validation and sanitization	☐
Audit logging	☐
Rate limiting	☐
Data encryption	☐
Security headers configured	☐

Performance Standards 

Requirement	Status
Constant-time database queries	☐
Query optimization implemented	☐
Effective caching strategy	☐
Pagination performance optimized	☐
Response time monitoring	☐
Memory usage optimized	☐
Database indexing proper	☐
No N+1 query problems	☐

Testing Coverage 

Requirement	Status
100% endpoint test coverage	☐
Positive and negative test cases	☐
Permission testing complete	☐
Performance testing implemented	☐
Security testing coverage	☐
Integration testing	☐
Load testing completed	☐
Automated test execution	☐

References 

Django REST Framework Documentation: https://www.django-rest-framework.org/
OpenAPI Specification: https://swagger.io/specification/
HTTP Status Code Definitions: https://tools.ietf.org/html/rfc7231#section-6
OAuth 2.0 Authorization Framework: https://tools.ietf.org/html/rfc6749
JWT Best Practices: https://tools.ietf.org/html/rfc8725
AWX Source Code: https://github.com/ansible/awx

Document Maintainer: API Development Team
Last Updated: September 2025
Review Schedule: Quarterly
Compliance Audit: Monthly