senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[BE-SVC-019] be-svc: Implement API versioning strategy

Browse source 
- Created VersionManager for managing API versions
- Added VersionMiddleware for automatic version detection:
  - X-API-Version header
  - Accept header (application/vnd.veza.v1+json)
  - URL path (/api/v1/...)
- Added support for deprecated versions with sunset dates
- Added /api/versions endpoint for version information
- Added helpers: GetAPIVersion, GetAPIVersionInfo
- Comprehensive unit tests for versioning system
- Integrated version manager in APIRouter

Phase: PHASE-6
Priority: P2
Progress: 115/267 (43.07%)
This commit is contained in:
senke 2025-12-24 17:07:30 +01:00
parent aa200c0864
commit 288a11bce9
4 changed files with 500 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
VEZA_COMPLETE_MVP_TODOLIST.json
View file

@ -4262,7 +4262,7 @@
"description": "Add proper API versioning for future compatibility",
"owner": "backend",
"estimated_hours": 4,
"status": "todo",
"status": "completed",
"files_involved": [],
"implementation_steps": [
{
@ -4283,7 +4283,19 @@
"Unit tests",
"Integration tests"
],
"notes": ""
"notes": "",
"completion": {
"completed_at": "2025-12-24T16:07:28.324972+00:00",
"actual_hours": 3.5,
"commits": [],
"files_changed": [
"veza-backend-api/internal/api/versioning.go",
"veza-backend-api/internal/api/versioning_test.go",
"veza-backend-api/internal/api/router.go"
],
"notes": "Implemented API versioning strategy with VersionManager, middleware for version detection (header, Accept header, URL path), deprecated version warnings, and version info endpoint.",
"issues_encountered": []
}
},
{
"id": "BE-SVC-020",
@ -11047,11 +11059,11 @@
]
},
"progress_tracking": {
"completed": 114,
"completed": 115,
"in_progress": 0,
"todo": 153,
"todo": 152,
"blocked": 0,
"last_updated": "2025-12-24T16:05:28.928926+00:00",
"completion_percentage": 42.69662921348314
"last_updated": "2025-12-24T16:07:28.325007+00:00",
"completion_percentage": 43.07116104868914
}
}

23
veza-backend-api/internal/api/router.go
View file

@ -39,18 +39,21 @@ import (
// APIRouter gère la configuration des routes de l'API
type APIRouter struct {
db *database.Database
config *config.Config
engine *gin.Engine
logger *zap.Logger
db *database.Database
config *config.Config
engine *gin.Engine
logger *zap.Logger
versionManager *VersionManager // BE-SVC-019: API versioning manager
}
// NewAPIRouter crée une nouvelle instance de APIRouter
func NewAPIRouter(db *database.Database, cfg *config.Config) *APIRouter {
logger := zap.L()
return &APIRouter{
db: db,
config: cfg,
logger: zap.L(),
db: db,
config: cfg,
logger: logger,
versionManager: NewVersionManager(logger), // BE-SVC-019: Initialize version manager
}
}
@ -161,6 +164,12 @@ func (r *APIRouter) Setup(router *gin.Engine) error {
// Swagger Documentation
router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
// BE-SVC-019: API versioning endpoint (before version middleware)
router.GET("/api/versions", VersionInfoHandler(r.versionManager))
// BE-SVC-019: Apply version middleware to API routes
router.Use(VersionMiddleware(r.versionManager))
// Routes core publiques (health, metrics, upload info)
r.setupCorePublicRoutes(router)

257
veza-backend-api/internal/api/versioning.go Normal file
View file

@ -0,0 +1,257 @@
package api
import (
"net/http"
"strings"
"github.com/gin-gonic/gin"
"go.uber.org/zap"
)
const (
// APIVersionHeader est le header HTTP pour spécifier la version de l'API
APIVersionHeader = "X-API-Version"
// AcceptHeaderVersion est le header Accept avec version (ex: application/vnd.veza.v1+json)
AcceptHeaderVersion = "Accept"
// DefaultAPIVersion est la version par défaut de l'API
DefaultAPIVersion = "v1"
// APIVersionKey est la clé utilisée pour stocker la version dans le contexte Gin
APIVersionKey = "api_version"
)
// APIVersion représente une version de l'API
type APIVersion struct {
Version string // Ex: "v1", "v2"
Deprecated bool // Indique si la version est dépréciée
SunsetDate string // Date de fin de support (RFC3339)
Description string // Description de la version
}
// VersionManager gère les versions de l'API (BE-SVC-019)
type VersionManager struct {
versions map[string]*APIVersion
defaultVersion string
logger *zap.Logger
}
// NewVersionManager crée un nouveau gestionnaire de versions
func NewVersionManager(logger *zap.Logger) *VersionManager {
vm := &VersionManager{
versions: make(map[string]*APIVersion),
defaultVersion: DefaultAPIVersion,
logger: logger,
}
// Enregistrer les versions par défaut
vm.RegisterVersion(&APIVersion{
Version: "v1",
Deprecated: false,
Description: "Current stable API version",
})
return vm
}
// RegisterVersion enregistre une nouvelle version de l'API
func (vm *VersionManager) RegisterVersion(version *APIVersion) {
vm.versions[version.Version] = version
vm.logger.Info("API version registered",
zap.String("version", version.Version),
zap.Bool("deprecated", version.Deprecated),
zap.String("description", version.Description))
}
// GetVersion retourne les informations sur une version
func (vm *VersionManager) GetVersion(version string) (*APIVersion, bool) {
v, exists := vm.versions[version]
return v, exists
}
// GetDefaultVersion retourne la version par défaut
func (vm *VersionManager) GetDefaultVersion() string {
return vm.defaultVersion
}
// SetDefaultVersion définit la version par défaut
func (vm *VersionManager) SetDefaultVersion(version string) {
if _, exists := vm.versions[version]; exists {
vm.defaultVersion = version
}
}
// GetAllVersions retourne toutes les versions disponibles
func (vm *VersionManager) GetAllVersions() map[string]*APIVersion {
result := make(map[string]*APIVersion)
for k, v := range vm.versions {
result[k] = v
}
return result
}
// VersionMiddleware est un middleware pour gérer le versioning de l'API (BE-SVC-019)
// Supporte plusieurs méthodes de spécification de version :
// 1. Header X-API-Version
// 2. Header Accept: application/vnd.veza.v1+json
// 3. URL path: /api/v1/...
func VersionMiddleware(versionManager *VersionManager) gin.HandlerFunc {
return func(c *gin.Context) {
// Extraire la version depuis différentes sources
version := extractAPIVersion(c)
// Valider la version
if version == "" {
version = versionManager.GetDefaultVersion()
}
// Vérifier si la version existe
apiVersion, exists := versionManager.GetVersion(version)
if !exists {
c.JSON(http.StatusBadRequest, gin.H{
"error": "Unsupported API version",
"version": version,
"available_versions": getAvailableVersions(versionManager),
})
c.Abort()
return
}
// Stocker la version dans le contexte
c.Set(APIVersionKey, version)
c.Set("api_version_info", apiVersion)
// Ajouter des headers de réponse pour indiquer la version utilisée
c.Header(APIVersionHeader, version)
if apiVersion.Deprecated {
c.Header("X-API-Version-Deprecated", "true")
if apiVersion.SunsetDate != "" {
c.Header("Sunset", apiVersion.SunsetDate)
}
}
// Logger si version dépréciée
if apiVersion.Deprecated {
versionManager.logger.Warn("Deprecated API version used",
zap.String("version", version),
zap.String("path", c.Request.URL.Path),
zap.String("sunset_date", apiVersion.SunsetDate))
}
c.Next()
}
}
// extractAPIVersion extrait la version de l'API depuis différentes sources
func extractAPIVersion(c *gin.Context) string {
// 1. Header X-API-Version
if version := c.GetHeader(APIVersionHeader); version != "" {
return normalizeVersion(version)
}
// 2. Header Accept: application/vnd.veza.v1+json
if accept := c.GetHeader(AcceptHeaderVersion); accept != "" {
if version := parseAcceptHeader(accept); version != "" {
return version
}
}
// 3. URL path: /api/v1/... ou /api/v2/...
path := c.Request.URL.Path
if strings.HasPrefix(path, "/api/") {
parts := strings.Split(path, "/")
if len(parts) >= 3 && strings.HasPrefix(parts[2], "v") {
return normalizeVersion(parts[2])
}
}
return ""
}
// normalizeVersion normalise une version (v1 -> v1, 1 -> v1, etc.)
func normalizeVersion(version string) string {
version = strings.TrimSpace(version)
version = strings.ToLower(version)
if !strings.HasPrefix(version, "v") {
version = "v" + version
}
return version
}
// parseAcceptHeader parse le header Accept pour extraire la version
// Format: application/vnd.veza.v1+json
func parseAcceptHeader(accept string) string {
parts := strings.Split(accept, ",")
for _, part := range parts {
part = strings.TrimSpace(part)
// Chercher le pattern vnd.veza.vX
if strings.Contains(part, "vnd.veza.v") {
start := strings.Index(part, "vnd.veza.v")
if start != -1 {
start += len("vnd.veza.v")
end := start
for end < len(part) && (part[end] >= '0' && part[end] <= '9') {
end++
}
if end > start {
return normalizeVersion("v" + part[start:end])
}
}
}
}
return ""
}
// getAvailableVersions retourne la liste des versions disponibles
func getAvailableVersions(vm *VersionManager) []string {
versions := make([]string, 0, len(vm.versions))
for v := range vm.versions {
versions = append(versions, v)
}
return versions
}
// GetAPIVersion retourne la version de l'API depuis le contexte Gin
func GetAPIVersion(c *gin.Context) string {
if version, exists := c.Get(APIVersionKey); exists {
if v, ok := version.(string); ok {
return v
}
}
return DefaultAPIVersion
}
// GetAPIVersionInfo retourne les informations complètes sur la version depuis le contexte
func GetAPIVersionInfo(c *gin.Context) *APIVersion {
if info, exists := c.Get("api_version_info"); exists {
if apiVersion, ok := info.(*APIVersion); ok {
return apiVersion
}
}
return nil
}
// VersionInfoHandler retourne les informations sur les versions disponibles
func VersionInfoHandler(versionManager *VersionManager) gin.HandlerFunc {
return func(c *gin.Context) {
versions := versionManager.GetAllVersions()
response := gin.H{
"current_version": versionManager.GetDefaultVersion(),
"versions": make(map[string]interface{}),
}
for version, info := range versions {
versionInfo := gin.H{
"version": info.Version,
"deprecated": info.Deprecated,
"description": info.Description,
}
if info.SunsetDate != "" {
versionInfo["sunset_date"] = info.SunsetDate
}
response["versions"].(map[string]interface{})[version] = versionInfo
}
c.JSON(http.StatusOK, response)
}
}

209
veza-backend-api/internal/api/versioning_test.go Normal file
View file

@ -0,0 +1,209 @@
package api
import (
"net/http"
"net/http/httptest"
"testing"
"github.com/gin-gonic/gin"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"go.uber.org/zap"
)
func TestNewVersionManager(t *testing.T) {
logger, _ := zap.NewDevelopment()
vm := NewVersionManager(logger)
assert.NotNil(t, vm)
assert.Equal(t, DefaultAPIVersion, vm.GetDefaultVersion())
assert.NotEmpty(t, vm.GetAllVersions())
}
func TestVersionManager_RegisterVersion(t *testing.T) {
logger, _ := zap.NewDevelopment()
vm := NewVersionManager(logger)
version := &APIVersion{
Version: "v2",
Deprecated: false,
Description: "New API version",
}
vm.RegisterVersion(version)
retrieved, exists := vm.GetVersion("v2")
require.True(t, exists)
assert.Equal(t, version, retrieved)
}
func TestVersionManager_GetVersion_NotFound(t *testing.T) {
logger, _ := zap.NewDevelopment()
vm := NewVersionManager(logger)
_, exists := vm.GetVersion("v99")
assert.False(t, exists)
}
func TestNormalizeVersion(t *testing.T) {
tests := []struct {
input string
expected string
}{
{"v1", "v1"},
{"1", "v1"},
{"V1", "v1"},
{" v2 ", "v2"},
{"2", "v2"},
}
for _, tt := range tests {
t.Run(tt.input, func(t *testing.T) {
result := normalizeVersion(tt.input)
assert.Equal(t, tt.expected, result)
})
}
}
func TestParseAcceptHeader(t *testing.T) {
tests := []struct {
name string
accept string
expected string
}{
{
name: "vnd.veza.v1",
accept: "application/vnd.veza.v1+json",
expected: "v1",
},
{
name: "vnd.veza.v2",
accept: "application/vnd.veza.v2+json",
expected: "v2",
},
{
name: "multiple accept types",
accept: "application/json, application/vnd.veza.v1+json",
expected: "v1",
},
{
name: "no version",
accept: "application/json",
expected: "",
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
result := parseAcceptHeader(tt.accept)
assert.Equal(t, tt.expected, result)
})
}
}
func TestVersionMiddleware_HeaderXAPIVersion(t *testing.T) {
gin.SetMode(gin.TestMode)
logger, _ := zap.NewDevelopment()
vm := NewVersionManager(logger)
router := gin.New()
router.Use(VersionMiddleware(vm))
router.GET("/test", func(c *gin.Context) {
version := GetAPIVersion(c)
c.JSON(200, gin.H{"version": version})
})
w := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/test", nil)
req.Header.Set(APIVersionHeader, "v1")
router.ServeHTTP(w, req)
assert.Equal(t, http.StatusOK, w.Code)
assert.Equal(t, "v1", w.Header().Get(APIVersionHeader))
}
func TestVersionMiddleware_AcceptHeader(t *testing.T) {
gin.SetMode(gin.TestMode)
logger, _ := zap.NewDevelopment()
vm := NewVersionManager(logger)
router := gin.New()
router.Use(VersionMiddleware(vm))
router.GET("/test", func(c *gin.Context) {
version := GetAPIVersion(c)
c.JSON(200, gin.H{"version": version})
})
w := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/test", nil)
req.Header.Set(AcceptHeaderVersion, "application/vnd.veza.v1+json")
router.ServeHTTP(w, req)
assert.Equal(t, http.StatusOK, w.Code)
}
func TestVersionMiddleware_InvalidVersion(t *testing.T) {
gin.SetMode(gin.TestMode)
logger, _ := zap.NewDevelopment()
vm := NewVersionManager(logger)
router := gin.New()
router.Use(VersionMiddleware(vm))
router.GET("/test", func(c *gin.Context) {
c.JSON(200, gin.H{"ok": true})
})
w := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/test", nil)
req.Header.Set(APIVersionHeader, "v99")
router.ServeHTTP(w, req)
assert.Equal(t, http.StatusBadRequest, w.Code)
}
func TestVersionMiddleware_DeprecatedVersion(t *testing.T) {
gin.SetMode(gin.TestMode)
logger, _ := zap.NewDevelopment()
vm := NewVersionManager(logger)
// Enregistrer une version dépréciée
vm.RegisterVersion(&APIVersion{
Version: "v0",
Deprecated: true,
SunsetDate: "2025-12-31T00:00:00Z",
Description: "Deprecated version",
})
router := gin.New()
router.Use(VersionMiddleware(vm))
router.GET("/test", func(c *gin.Context) {
c.JSON(200, gin.H{"ok": true})
})
w := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/test", nil)
req.Header.Set(APIVersionHeader, "v0")
router.ServeHTTP(w, req)
assert.Equal(t, http.StatusOK, w.Code)
assert.Equal(t, "true", w.Header().Get("X-API-Version-Deprecated"))
assert.Equal(t, "2025-12-31T00:00:00Z", w.Header().Get("Sunset"))
}
func TestVersionInfoHandler(t *testing.T) {
gin.SetMode(gin.TestMode)
logger, _ := zap.NewDevelopment()
vm := NewVersionManager(logger)
router := gin.New()
router.GET("/api/versions", VersionInfoHandler(vm))
w := httptest.NewRecorder()
req := httptest.NewRequest("GET", "/api/versions", nil)
router.ServeHTTP(w, req)
assert.Equal(t, http.StatusOK, w.Code)
assert.Contains(t, w.Body.String(), "current_version")
assert.Contains(t, w.Body.String(), "versions")
}