api-patterns

API Development Guidelines

RESTful API Design

Endpoint Conventions

Follow the patterns established in backend/internal/api/routes.go:

Resource Naming

• Use plural nouns for resources: /api/v1/orders, /api/v1/products
• Use kebab-case for multi-word resources: /api/v1/dining-tables
• Nest related resources: /api/v1/orders/{id}/payments
• Use descriptive action names for non-CRUD operations: /api/v1/orders/{id}/status

HTTP Methods

Standard CRUD operations:

GET    /api/v1/orders           # List all orders
POST   /api/v1/orders           # Create new order
GET    /api/v1/orders/{id}      # Get specific order
PUT    /api/v1/orders/{id}      # Update entire order
PATCH  /api/v1/orders/{id}      # Partial update
DELETE /api/v1/orders/{id}      # Delete order

# Action-specific endpoints
PATCH  /api/v1/orders/{id}/status     # Update order status
POST   /api/v1/orders/{id}/payments   # Add payment to order

Request/Response Patterns

Standard Response Format

Use consistent response structure from models/models.go:

{
  "success": true,
  "message": "Order created successfully",
  "data": {
    "id": "uuid-here",
    "order_number": "ORD001",
    // ... other fields
  }
}

Error Response Format

{
  "success": false,
  "message": "User-friendly error message",
  "error": "error_code_for_clients"
}

Pagination Response Format

{
  "success": true,
  "message": "Orders retrieved successfully",
  "data": [...],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  }
}

Authentication & Authorization

JWT Token Authentication

Follow patterns from middleware/auth.go:

Request Headers

Authorization: Bearer <jwt_token>
Content-Type: application/json
Accept: application/json

Role-Based Access Control

// Public routes - no authentication
public.POST("/auth/login", authHandler.Login)

// Protected routes - authentication required
protected.GET("/orders", orderHandler.GetOrders)

// Admin routes - specific roles required
admin.Use(middleware.RequireRoles([]string{"admin", "manager"}))
admin.GET("/dashboard/stats", getDashboardStats)