# Fullstack API Contract

> Maintain consistency between frontend and backend APIs across multiple frameworks (Spring Boot, Django, Flask) and TypeScript frontends. Use when developers need to define API contracts, generate backend code (controllers, DTOs, serializers), generate TypeScript types and API clients, validate request/response consistency, or solve mismatched API problems between AI-generated frontend and backend code.

- Skill: `reisen7/fullstack-api-contract` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add reisen7/fullstack-api-contract`
- Raw SKILL.md: https://api.skillmd.com/api/skills/reisen7/fullstack-api-contract/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: reisen7 (https://skillmd.com/u/reisen7)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/reisen7/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](references/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:

```bash
python scripts/init_contract.py my-api
```

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

```yaml
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](references/CONTRACT-TEMPLATE.md) for examples.

### Step 2: Generate Backend Code

**Spring Boot:**
```bash
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](references/SPRING-BOOT.md) for patterns and customization.

**Django REST Framework:**
```bash
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](references/DJANGO.md) for patterns and customization.

**Flask:**
```bash
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](references/FLASK.md) for patterns and customization.

### Step 3: Generate Frontend Code

```bash
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](references/TYPESCRIPT.md) for usage examples.

### Step 4: Validate Consistency

```bash
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:

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

**Success response:**
```json
{
  "success": true,
  "data": { "id": "123", "name": "John" }
}
```

**Error response:**
```json
{
  "success": false,
  "error": "User not found"
}
```

## Common Patterns

### Authentication

See [AUTH-PATTERNS.md](references/AUTH-PATTERNS.md) for:
- JWT token handling
- OAuth2 flows
- API key authentication
- Session management

### Pagination

See [PAGINATION.md](references/PAGINATION.md) for:
- Cursor-based pagination
- Offset-based pagination
- Response envelope format

### Error Handling

See [ERROR-HANDLING.md](references/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:

```bash
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.