Cursor rule

1---
2description: RESTful API design patterns and conventions for POS System
3---
4 
5# API Development Guidelines
6 
7## RESTful API Design
8 
9### Endpoint Conventions
10Follow the patterns established in [backend/internal/api/routes.go](mdc:backend/internal/api/routes.go):
11 
12### Resource Naming
13- Use plural nouns for resources: `/api/v1/orders`, `/api/v1/products`
14- Use kebab-case for multi-word resources: `/api/v1/dining-tables`
15- Nest related resources: `/api/v1/orders/{id}/payments`
16- Use descriptive action names for non-CRUD operations: `/api/v1/orders/{id}/status`
17 
18### HTTP Methods
19Standard CRUD operations:
20```
21GET    /api/v1/orders           # List all orders
22POST   /api/v1/orders           # Create new order
23GET    /api/v1/orders/{id}      # Get specific order
24PUT    /api/v1/orders/{id}      # Update entire order
25PATCH  /api/v1/orders/{id}      # Partial update
26DELETE /api/v1/orders/{id}      # Delete order
27 
28# Action-specific endpoints
29PATCH  /api/v1/orders/{id}/status     # Update order status
30POST   /api/v1/orders/{id}/payments   # Add payment to order
31```
32 
33## Request/Response Patterns
34 
35### Standard Response Format
36Use consistent response structure from [models/models.go](mdc:backend/internal/models/models.go):
37 
38```json
39{
40  "success": true,
41  "message": "Order created successfully",
42  "data": {
43    "id": "uuid-here",
44    "order_number": "ORD001",
45    // ... other fields
46  }
47}
48```
49 
50### Error Response Format
51```json
52{
53  "success": false,
54  "message": "User-friendly error message",
55  "error": "error_code_for_clients"
56}
57```
58 
59### Pagination Response Format
60```json
61{
62  "success": true,
63  "message": "Orders retrieved successfully",
64  "data": [...],
65  "meta": {
66    "current_page": 1,
67    "per_page": 20,
68    "total": 150,
69    "total_pages": 8
70  }
71}
72```
73 
74## Authentication & Authorization
75 
76### JWT Token Authentication
77Follow patterns from [middleware/auth.go](mdc:backend/internal/middleware/auth.go):
78 
79### Request Headers
80```
81Authorization: Bearer <jwt_token>
82Content-Type: application/json
83Accept: application/json
84```
85 
86### Role-Based Access Control
87```go
88// Public routes - no authentication
89public.POST("/auth/login", authHandler.Login)
90 
91// Protected routes - authentication required
92protected.GET("/orders", orderHandler.GetOrders)
93 
94// Admin routes - specific roles required
95admin.Use(middleware.RequireRoles([]string{"admin", "manager"}))
96admin.GET("/dashboard/stats", getDashboardStats)
97```
98 
99## Query Parameters & Filtering
100 
101### Standard Query Parameters
102```
103GET /api/v1/orders?page=1&per_page=20&status=pending&order_type=dine_in
104```
105 
106### Common Parameters
107- `page` - Page number for pagination (default: 1)
108- `per_page` - Items per page (default: 20, max: 100)
109- `sort` - Sort field and direction: `sort=created_at:desc`
110- `search` - Text search across relevant fields
111- Resource-specific filters (status, type, date ranges, etc.)
112 
113### Date Filtering
114```
115GET /api/v1/orders?created_after=2024-01-01&created_before=2024-12-31
116```
117 
118## Error Handling
119 
120### HTTP Status Codes
121Use appropriate status codes consistently:
122```
123200 OK              - Successful GET, PUT, PATCH
124201 Created         - Successful POST
125204 No Content      - Successful DELETE
126400 Bad Request     - Invalid request data
127401 Unauthorized    - Authentication required/failed  
128403 Forbidden       - Insufficient permissions
129404 Not Found       - Resource doesn't exist
130409 Conflict        - Resource conflict (duplicate, etc.)
131422 Unprocessable   - Valid JSON but business logic error
132500 Internal Error  - Server error
133```
134 
135### Error Response Examples
136```go
137// Validation error
138c.JSON(http.StatusBadRequest, models.APIResponse{
139    Success: false,
140    Message: "Order must contain at least one item",
141    Error:   stringPtr("empty_order"),
142})
143 
144// Resource not found
145c.JSON(http.StatusNotFound, models.APIResponse{
146    Success: false,
147    Message: "Order not found",
148    Error:   stringPtr("order_not_found"),
149})
150 
151// Permission error
152c.JSON(http.StatusForbidden, models.APIResponse{
153    Success: false,
154    Message: "Insufficient permissions",
155    Error:   stringPtr("insufficient_permissions"),
156})
157```
158 
159## Request Validation
160 
161### Input Validation Pattern
162```go
163type CreateOrderRequest struct {
164    TableID      *uuid.UUID         `json:"table_id"`
165    CustomerName *string            `json:"customer_name"`
166    OrderType    string             `json:"order_type"`
167    Items        []CreateOrderItem  `json:"items"`
168    Notes        *string            `json:"notes"`
169}
170 
171func (h *OrderHandler) CreateOrder(c *gin.Context) {
172    var req CreateOrderRequest
173    if err := c.ShouldBindJSON(&req); err != nil {
174        c.JSON(http.StatusBadRequest, models.APIResponse{
175            Success: false,
176            Message: "Invalid request body",
177            Error:   stringPtr(err.Error()),
178        })
179        return
180    }
181    
182    // Additional business logic validation
183    if len(req.Items) == 0 {
184        c.JSON(http.StatusBadRequest, models.APIResponse{
185            Success: false,
186            Message: "Order must contain at least one item",
187            Error:   stringPtr("empty_order"),
188        })
189        return
190    }
191}
192```
193 
194## Database Transaction Patterns
195 
196### Transaction Usage
197Use transactions for multi-table operations:
198```go
199func (h *OrderHandler) CreateOrder(c *gin.Context) {
200    tx, err := h.db.Begin()
201    if err != nil {
202        // Handle error
203        return
204    }
205    defer tx.Rollback() // Always rollback if not committed
206    
207    // Multiple database operations
208    _, err = tx.Exec("INSERT INTO orders ...")
209    if err != nil {
210        // Error will cause rollback
211        return
212    }
213    
214    _, err = tx.Exec("INSERT INTO order_items ...")
215    if err != nil {
216        return
217    }
218    
219    // Commit transaction
220    if err := tx.Commit(); err != nil {
221        // Handle commit error
222        return
223    }
224}
225```
226 
227## API Documentation
228 
229### Endpoint Documentation
230Document each endpoint with:
231- Purpose and description
232- Required permissions/roles
233- Request format and validation rules
234- Response format and possible status codes
235- Example requests and responses
236 
237### Request/Response Examples
238```go
239// CreateOrder creates a new order
240// @Summary Create a new order
241// @Description Create a new customer order with items and table assignment
242// @Tags orders
243// @Accept json
244// @Produce json
245// @Param order body CreateOrderRequest true "Order data"
246// @Success 201 {object} APIResponse{data=Order}
247// @Failure 400 {object} APIResponse
248// @Failure 401 {object} APIResponse
249// @Router /api/v1/orders [post]
250```
251 
252## Performance Considerations
253 
254### Query Optimization
255- Use database indexes for frequently filtered fields
256- Implement pagination for large result sets
257- Avoid N+1 query problems with proper JOINs
258- Cache expensive computations
259 
260### Response Optimization
261- Use appropriate HTTP caching headers
262- Compress responses when beneficial
263- Return only necessary fields (consider field selection)
264- Use ETags for conditional requests
265 
266## Rate Limiting & Throttling
267 
268### Rate Limiting Strategy
269```go
270// Implement rate limiting middleware
271func RateLimitMiddleware() gin.HandlerFunc {
272    // Rate limiting implementation
273    // Consider user-based, IP-based, or endpoint-based limits
274}
275 
276// Apply to sensitive endpoints
277protected.Use(RateLimitMiddleware())
278```
279 
280## API Versioning
281 
282### URL Versioning
283Current API uses URL path versioning:
284```
285/api/v1/orders    # Version 1
286/api/v2/orders    # Version 2 (future)
287```
288 
289### Backward Compatibility
290- Maintain backward compatibility within major versions
291- Deprecate old endpoints gracefully with proper warnings
292- Document breaking changes and migration paths
293- Support multiple versions during transition periods
294 
295## Monitoring & Logging
296 
297### Request Logging
298Log important API operations:
299```go
300// Log successful operations
301log.Printf("Order created: user_id=%s, order_id=%s", userID, orderID)
302 
303// Log errors with context
304log.Printf("Failed to create order: user_id=%s, error=%s", userID, err.Error())
305```
306 
307### Metrics Collection
308Track key metrics:
309- Request/response times
310- Error rates by endpoint
311- Authentication success/failure rates
312- Resource creation/modification rates
313- Database query performance