Backend to Frontend System

A collaborative skill for documenting and communicating data requirements between frontend and backend engineers. Covers API contract design, data shape specifications, request/response schemas, and establishing clear handoff documentation.

When to Use This Skill

Choose this skill when:

• Documenting what data the frontend needs from the backend
• Designing API contracts before implementation begins
• Creating data requirement specifications for backend teams
• Establishing consistent data exchange formats between teams
• Resolving frontend-backend integration mismatches

Consider alternatives when:

• Implementing API endpoints → use a backend/API skill
• Building frontend components → use a frontend framework skill
• Designing database schemas → use a database design skill
• Writing API documentation → use an OpenAPI/Swagger skill

Quick Start

Copy
// Frontend Data Requirements Document

/**
 * Feature: User Dashboard
 *
 * WHAT I NEED (frontend perspective):
 * - Current user profile with avatar URL
 * - List of recent activities (last 7 days)
 * - Summary statistics (total posts, followers, following)
 * - Notification count (unread)
 *
 * HOW I'LL CALL IT:
 * GET /api/dashboard
 * Authorization: Bearer {token}
 *
 * WHAT I EXPECT BACK:
 */
interface DashboardResponse {
  user: {
    id: string;
    name: string;
    avatarUrl: string;
    email: string;
  };
  stats: {
    totalPosts: number;
    followers: number;
    following: number;
  };
  recentActivity: Array<{
    id: string;
    type: 'post' | 'comment' | 'like';
    description: string;
    timestamp: string; // ISO 8601
  }>;
  notifications: {
    unreadCount: number;
  };
}

Core Concepts

Data Requirements Template

Section	Frontend Provides	Backend Implements
Endpoint	URL path + method	Route handler
Auth	Token type needed	Auth middleware
Request	Query params, body shape	Validation schema
Response	Expected data shape	Serializer/transformer
Errors	UI needs per error	Error responses
Pagination	Page size, cursor handling	Query limits, cursors
Caching	Freshness tolerance	Cache headers

API Contract Specification

Copy
// Contract: Product Search
// Frontend: needs to search products with filters
// Backend: implements the query and returns paginated results

// REQUEST
interface SearchRequest {
  query: string;           // Required: search term
  category?: string;       // Optional: filter by category
  minPrice?: number;       // Optional: minimum price
  maxPrice?: number;       // Optional: maximum price
  sortBy?: 'price' | 'rating' | 'newest'; // Default: 'relevance'
  page?: number;           // Default: 1
  limit?: number;          // Default: 20, max: 100
}

// RESPONSE
interface SearchResponse {
  products: Product[];     // Array of matching products
  pagination: {
    page: number;
    limit: number;
    total: number;         // Total matching products
    hasMore: boolean;      // More pages available?
  };
  facets: {                // For filter UI
    categories: Array<{ name: string; count: number }>;
    priceRange: { min: number; max: number };
  };
}

// ERROR RESPONSES
// 400: { error: 'INVALID_QUERY', message: 'Search query too short (min 2 chars)' }
// 429: { error: 'RATE_LIMITED', retryAfter: 60 }

Handoff Documentation Pattern

Copy
# API Handoff: User Settings

## What the Frontend Needs

### Read Settings
- **Endpoint:** `GET /api/users/me/settings`
- **When called:** Page load on settings screen
- **Expected latency:** < 500ms (cache this response)
- **Refresh frequency:** On page focus

### Update Settings
- **Endpoint:** `PATCH /api/users/me/settings`
- **When called:** On save button click (debounced, not on every change)
- **Optimistic update:** Yes, show changes immediately, revert on error
- **Validation:** Frontend validates before sending, backend re-validates

## What the Frontend Shows on Error
| Status | Frontend Action |
|--------|----------------|
| 401 | Redirect to login |
| 403 | Show "permission denied" toast |
| 422 | Show field-level validation errors |
| 500 | Show "try again later" toast |

Configuration

Parameter	Type	Default	Description
specFormat	string	'typescript'	Contract format: typescript, json-schema, or openapi
paginationStyle	string	'offset'	Pagination: offset, cursor, or keyset
dateFormat	string	'iso8601'	Date serialization format
errorFormat	string	'structured'	Errors: structured JSON or HTTP status only
cacheStrategy	string	'etag'	Caching: etag, last-modified, or max-age
versioningStyle	string	'url'	API versioning: url (/v2), header, or query param

Best Practices

1. Frontend describes the "what," backend decides the "how" — Frontend documents what data shapes and behaviors it needs. Backend decides the implementation (queries, joins, caching). Don't prescribe database schema in frontend requirements.

2. Define error responses for every endpoint — The frontend needs to know what errors to handle and what to show the user. Document every possible error status, code, and the UI response for each.

3. Use TypeScript interfaces as the contract language — TypeScript interfaces are readable by both frontend and backend engineers. They serve as both documentation and can be used for runtime validation with tools like Zod.

4. Specify pagination requirements upfront — Infinite scroll needs cursor-based pagination. Page numbers need offset-based. Total counts need a total field. Agreeing on pagination style before implementation prevents rework.

5. Include real example payloads in the specification — Abstract type definitions miss edge cases. Include 2-3 real example responses showing populated fields, empty arrays, null optional fields, and error responses.

Common Issues

Frontend and backend have different field names — Frontend uses camelCase, backend returns snake_case. Agree on a serialization convention (usually camelCase for JSON APIs) and transform at the API boundary, not in every component.

Optional fields handled differently — Frontend expects null for missing data, backend sends undefined (omits the field). Agree on conventions: always send the field with null, or always omit missing fields.

Response shape changes without warning — Backend changes a field from string to object and breaks the frontend. Use versioned API contracts and treat response shape changes as breaking changes requiring coordination.