Coverage for src / mcp_server_langgraph / api / version.py: 100%

1""" 

2API Version Metadata Endpoint 

3 

4Provides version information for API clients to determine compatibility and features. 

5Supports semantic versioning and breaking change detection. 

6""" 

7 

8from fastapi import APIRouter 

9from pydantic import BaseModel, Field 

10 

11from mcp_server_langgraph.core.config import settings 

12 

13router = APIRouter(prefix="/api", tags=["API Metadata"]) 

14 

15 

16class APIVersionInfo(BaseModel): 

17 """ 

18 API version metadata 

19 

20 Follows semantic versioning (MAJOR.MINOR.PATCH): 

21 - MAJOR: Breaking changes (incompatible API changes) 

22 - MINOR: New features (backward-compatible) 

23 - PATCH: Bug fixes (backward-compatible) 

24 """ 

25 

26 version: str = Field(description="Application version (semantic versioning: MAJOR.MINOR.PATCH)", examples=["2.8.0"]) 

27 api_version: str = Field(description="Current API version (e.g., 'v1')", examples=["v1"]) 

28 supported_versions: list[str] = Field(description="List of supported API versions", examples=[["v1"]]) 

29 deprecated_versions: list[str] = Field( 

30 description="List of deprecated API versions (still functional but will be removed)", 

31 default_factory=list, 

32 examples=[[]], 

33 ) 

34 sunset_dates: dict[str, str] = Field( 

35 description="Sunset dates for deprecated versions (ISO 8601 format)", default_factory=dict, examples=[{}] 

36 ) 

37 changelog_url: str | None = Field( 

38 None, description="URL to API changelog", examples=["https://docs.example.com/api/changelog"] 

39 ) 

40 documentation_url: str | None = Field( 

41 None, description="URL to API documentation", examples=["https://docs.example.com/api/v1"] 

42 ) 

43 

44 

45@router.get( 

46 "/version", 

47 summary="Get API version information", 

48 description=""" 

49 Returns API version metadata for client compatibility checking. 

50 

51 **Versioning Strategy:** 

52 - **Semantic Versioning**: MAJOR.MINOR.PATCH 

53 - **URL Versioning**: `/api/v1`, `/api/v2`, etc. 

54 - **Header Negotiation**: `X-API-Version: 1.0` (optional) 

55 - **Deprecation Policy**: 6-month sunset period for deprecated versions 

56 

57 **Breaking Changes:** 

58 - Removing fields from responses 

59 - Changing field types 

60 - Removing endpoints 

61 - Changing authentication methods 

62 

63 **Non-Breaking Changes:** 

64 - Adding new endpoints 

65 - Adding new optional fields to requests 

66 - Adding new fields to responses 

67 - Adding new query parameters (optional) 

68 

69 Use this endpoint to: 

70 - Check current API version 

71 - Determine if your client is compatible 

72 - Find out when deprecated versions will be removed 

73 - Locate API documentation 

74 """, 

75 responses={ 

76 200: { 

77 "description": "API version information", 

78 "content": { 

79 "application/json": { 

80 "example": { 

81 "version": "2.8.0", 

82 "api_version": "v1", 

83 "supported_versions": ["v1"], 

84 "deprecated_versions": [], 

85 "sunset_dates": {}, 

86 "changelog_url": None, 

87 "documentation_url": "/docs", 

88 } 

89 } 

90 }, 

91 } 

92 }, 

93 operation_id="get_api_version_metadata", 

94) 

95async def get_version() -> APIVersionInfo: 

96 """ 

97 Get API version metadata 

98 

99 Returns current version, supported versions, and deprecation information. 

100 """ 

101 return APIVersionInfo( 

102 version=settings.service_version, 

103 api_version="v1", 

104 supported_versions=["v1"], 

105 deprecated_versions=[], 

106 sunset_dates={}, 

107 changelog_url=None, 

108 documentation_url="/docs", 

109 )