Phase 3.4: API modernization (versioned REST API)

[renecannao]

Phase 3.4 — API Modernization

Goal: Versioned REST API (/api/v2/) with structured JSON responses, consistent error handling, and an OpenAPI spec.

Sub-tasks

• 3.4.1 Audit current API endpoints in go/http/api.go — catalog all routes, parameters, response formats
• 3.4.2 Design /api/v2/ URL structure — RESTful resource naming, consistent patterns
• 3.4.3 Define standard response envelope:

  {
   "status": "ok|error",
   "data": { ... },
   "error": { "code": "...", "message": "..." },
   "meta": { "page": 1, "total": 100 }
  }

• 3.4.4 Implement v2 router alongside existing v1 routes (both active simultaneously)
• 3.4.5 Migrate cluster endpoints: /api/v2/clusters, /api/v2/clusters/{name}
• 3.4.6 Migrate instance endpoints: /api/v2/instances, /api/v2/instances/{host}/{port}
• 3.4.7 Migrate topology endpoints: /api/v2/topology/{cluster}
• 3.4.8 Migrate recovery endpoints: /api/v2/recoveries, /api/v2/recoveries/{id}
• 3.4.9 Add pagination support for list endpoints
• 3.4.10 Add filtering and sorting query parameters
• 3.4.11 Create OpenAPI/Swagger spec (docs/api/openapi.yaml)
• 3.4.12 Add API documentation generation from OpenAPI spec
• 3.4.13 Deprecation headers on v1 endpoints pointing to v2 equivalents
• 3.4.14 API integration tests

Design considerations

• v1 API must remain functional — no breaking changes to existing consumers
• v2 should use proper HTTP status codes (v1 returns 200 for everything)
• Authentication should be consistent (existing auth mechanism applies to both)
• Consider rate limiting for v2 endpoints
• JSON responses should use camelCase (Go convention: marshal tags)

Dependencies

• Best done after Phase 3.4: API modernization (versioned REST API) #33 (Phase 3.6: Replace go-martini) since the router will change, but can start with interface design now

Part of Phase 3 — Feature Direction.