api-contract-define

Define API Contract Between Backend and Frontend

Feature: $ARGUMENTS

Task: Create detailed API contract specification for backend/frontend coordination

1. Define RESTful endpoints:

   Base URL: /api/v1/{feature}
   
   Endpoints:
   - GET /api/v1/{features}
     Query params: page, size, sort, filter
     Response: Page<{Feature}Response>
   
   - GET /api/v1/{features}/{id}
     Path param: id (Long)
     Response: {Feature}Response
   
   - POST /api/v1/{features}
     Body: {Feature}Request
     Response: {Feature}Response (201 Created)
   
   - PUT /api/v1/{features}/{id}
     Path param: id (Long)
     Body: {Feature}Request
     Response: {Feature}Response
   
   - DELETE /api/v1/{features}/{id}
     Path param: id (Long)
     Response: 204 No Content
   

2. Define request/response DTOs:

   // Request DTO (for POST/PUT)
   interface {Feature}Request {
     name: string;        // min: 2, max: 100
     description?: string; // max: 1000
     // Add domain-specific fields
   }
   
   // Response DTO (for GET)
   interface {Feature}Response {
     id: number;
     name: string;
     description?: string;
     createdAt: string;   // ISO 8601
     updatedAt: string;   // ISO 8601
     // Add computed fields
   }
   
   // Page response wrapper
   interface Page<T> {
     content: T[];
     totalElements: number;
     totalPages: number;
     size: number;
     number: number;
   }
   

3. Define error responses:

   {
     "timestamp": "2024-01-20T10:30:00Z",
     "status": 400,
     "error": "Bad Request",
     "message": "Validation failed",
     "path": "/api/v1/{features}",
     "errors": [
       {
         "field": "name",
         "message": "Name is required"
       }
     ]
   }
   

4. Define validation rules:

   • Backend: Bean Validation annotations
   • Frontend: Matching Zod schemas

   name: required, 2-100 chars
   description: optional, max 1000 chars
   email: valid email format
   date: ISO 8601 format