Course contentsShow
← AI Engineering
Lesson 1001 of 1,88624. Building AI APIsFree lesson

Semantic Versioning for AI APIs

Apply semantic versioning principles to API changes and model updates.

Semantic Versioning for AI APIs

You'll learn how to apply semantic versioning principles to manage AI API changes without breaking client applications.

What is Semantic Versioning for AI?

When you update an AI API—whether by changing model behavior, modifying response formats, or adjusting endpoints—you need a clear system to communicate the impact of those changes. Semantic versioning (SemVer) uses a three-part version number: MAJOR.MINOR.PATCH (e.g., 2.3.1).

The Three Levels of Change

MAJOR version (2.x.x → 3.x.x): Breaking changes that require client code updates. Examples include:

  • Changing response schema structure
  • Removing endpoints or parameters
  • Switching to a fundamentally different model that alters output format

MINOR version (2.3.x → 2.4.x): Backward-compatible additions. Examples include:

  • Adding new optional parameters
  • Introducing new endpoints
  • Enhancing responses with additional (optional) fields

PATCH version (2.3.1 → 2.3.2): Backward-compatible bug fixes. Examples include:

  • Fixing error handling issues
  • Improving prompt templates without changing outputs
  • Performance optimizations

AI-Specific Considerations

Model updates create a unique challenge: even "identical" prompts might produce different outputs after retraining. Consider bumping the MINOR version when upgrading models if outputs remain functionally compatible, but increment MAJOR if response structure or reliability changes significantly.

Think of it like a restaurant menu: adding new dishes is MINOR, fixing a recipe error is PATCH, but completely changing the cuisine style is MAJOR.

Key Takeaway: Use semantic versioning to clearly communicate the risk level of AI API updates—MAJOR for breaking changes, MINOR for safe additions, PATCH for fixes—helping clients decide when to update their integration.