130 lines
3.0 KiB
Markdown
130 lines
3.0 KiB
Markdown
# Define API Contract Between Backend and Frontend
|
|
|
|
Feature: $ARGUMENTS
|
|
|
|
## Task: Create detailed API contract specification for backend/frontend coordination
|
|
|
|
1. **Define RESTful endpoints**:
|
|
|
|
```yaml
|
|
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**:
|
|
|
|
```typescript
|
|
// 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**:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
```
|
|
|
|
5. **Define status codes**:
|
|
- 200: OK (GET, PUT)
|
|
- 201: Created (POST)
|
|
- 204: No Content (DELETE)
|
|
- 400: Bad Request (validation)
|
|
- 404: Not Found
|
|
- 409: Conflict (duplicate)
|
|
- 500: Internal Server Error
|
|
|
|
6. **Integration requirements**:
|
|
- CORS: Allow frontend origin
|
|
- Content-Type: application/json
|
|
- Authentication: Bearer token (if needed)
|
|
- Pagination: Spring Pageable format
|
|
- Sorting: field,direction (e.g., "name,asc")
|
|
|
|
7. **Backend implementation notes**:
|
|
|
|
```java
|
|
// Entity fields match response DTO
|
|
// Use MapStruct for DTO mapping
|
|
// Repository method naming conventions
|
|
// Service layer validation
|
|
```
|
|
|
|
8. **Frontend implementation notes**:
|
|
```typescript
|
|
// Zod schemas match validation rules
|
|
// API client with base configuration
|
|
// TanStack Query hooks
|
|
// Error handling utilities
|
|
```
|
|
|
|
Save this contract as: `PRPs/working-memory/{feature-name}/contracts/{feature}-api-contract.md`
|
|
|
|
Share this file between backend and frontend teams for alignment.
|