Fullstack API Contract

Fullstack API Contract

Maintain API consistency between frontend and backend across Spring Boot, Django REST Framework, Flask, and TypeScript.

Quick Start

1. Define API contract using OpenAPI 3.0 (see CONTRACT-TEMPLATE.md)
2. Select backend framework (Spring Boot, Django, Flask)
3. Generate backend code using framework-specific scripts
4. Generate frontend code (TypeScript types + API client)
5. Validate consistency between frontend and backend

Workflow

Step 1: Define API Contract

Create an OpenAPI 3.0 YAML file defining your API endpoints:

python scripts/init_contract.py my-api

This creates my-api-contract.yaml with the standard response format:

components:
  schemas:
    ApiResponse:
      type: object
      required: [success]
      properties:
        success:
          type: boolean
        data:
          type: object
        error:
          type: string

Edit the contract to add your endpoints. See CONTRACT-TEMPLATE.md for examples.

Step 2: Generate Backend Code

Spring Boot:

python scripts/generate_springboot.py my-api-contract.yaml --output ./backend

Generates:

• Controllers with @RestController annotations
• DTOs with validation annotations
• Unified ApiResponse<T> wrapper
• Exception handlers

See SPRING-BOOT.md for patterns and customization.

Django REST Framework:

python scripts/generate_django.py my-api-contract.yaml --output ./backend

Generates:

• ViewSets with @api_view decorators
• Serializers with validation
• Unified response format
• Exception middleware

See DJANGO.md for patterns and customization.

Flask:

python scripts/generate_flask.py my-api-contract.yaml --output ./backend

Generates:

• Blueprint routes with decorators
• Marshmallow schemas
• Unified response helpers
• Error handlers

See FLASK.md for patterns and customization.

Step 3: Generate Frontend Code

python scripts/generate_typescript.py my-api-contract.yaml --output ./frontend/src/api

Generates:

• TypeScript interfaces for all schemas
• Type-safe API client with methods for each endpoint
• Axios-based HTTP client with interceptors
• Error handling utilities

See TYPESCRIPT.md for usage examples.

Step 4: Validate Consistency

python scripts/validate_contract.py my-api-contract.yaml --backend ./backend --frontend ./frontend

Validates:

• Request/response types match between frontend and backend
• All endpoints are implemented
• Error handling is consistent
• Authentication patterns are correct

Unified Response Format

All generated code uses this standard format:

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
}

Success response:

{
  "success": true,
  "data": { "id": "123", "name": "John" }
}

Error response:

{
  "success": false,
  "error": "User not found"
}

Common Patterns

Authentication

See AUTH-PATTERNS.md for:

• JWT token handling
• OAuth2 flows
• API key authentication
• Session management

Pagination

See PAGINATION.md for:

• Cursor-based pagination
• Offset-based pagination
• Response envelope format

Error Handling

See ERROR-HANDLING.md for:

• HTTP status code mapping
• Error code conventions
• Validation error format
• Exception handling patterns

Mock Data Generation

Generate mock data for testing:

python scripts/generate_mocks.py my-api-contract.yaml --output ./mocks

Creates:

• JSON mock responses for each endpoint
• Mock server configuration
• Test fixtures

Framework Selection Guide

Choose Spring Boot when:

• Building enterprise Java applications
• Need strong typing and compile-time safety
• Using Spring ecosystem (Security, Data, etc.)

Choose Django when:

• Building Python applications with ORM
• Need admin interface and batteries-included approach
• Using Django ecosystem

Choose Flask when:

• Building lightweight Python APIs
• Need flexibility and minimal boilerplate
• Microservices architecture

Troubleshooting

Type mismatches: Run validation script to identify inconsistencies Missing endpoints: Check contract YAML for typos in operationId Authentication errors: Verify auth patterns in contract match implementation

For detailed troubleshooting, see framework-specific reference files.