versioning

name	versioning
version	2.0.0
description	API versioning strategies and backward compatibility
sasmp_version	1.3.0
bonded_agent	01-api-architect
bond_type	PRIMARY_BOND
atomic_design	{"single_responsibility":"API versioning and deprecation management","boundaries":{"includes":["url_versioning","header_versioning","deprecation","migration"],"excludes":["api_design","implementation"]}}
parameter_validation	{"schema":{"type":"object","properties":{"strategy":{"type":"string","enum":["url","header","query"]},"version_format":{"type":"string","pattern":"^v?[0-9]+$"}}}}
retry_config	{"enabled":false}
logging	{"level":"INFO","fields":["version","strategy","deprecated"]}
dependencies	{"skills":["api-architecture"],"agents":["01-api-architect"]}

API Versioning Skill

Purpose

Choose and implement API versioning strategies.

Versioning Strategies

Strategy	Format	Pros	Cons
URL path	/api/v1/users	Clear, cacheable	URL pollution
Header	Accept: application/vnd.api.v1+json	Clean URLs	Hidden
Query param	/api/users?version=1	Flexible	Unconventional

URL Versioning (Recommended)

# Version in path
/api/v1/users        # Current stable
/api/v2/users        # New version
/api/v3-beta/users   # Pre-release

# Version-specific routing
app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);

Header Versioning

# Request
Accept: application/vnd.myapi.v1+json

# Response
Content-Type: application/vnd.myapi.v1+json

Deprecation Policy

# Sunset header
Sunset: Sat, 31 Dec 2025 23:59:59 GMT
Deprecation: true
Link: </api/v2/users>; rel="successor-version"

# Response body warning
{
  "data": {...},
  "warnings": [
    {
      "type": "deprecation",
      "message": ,
       
    }
  ]
}