Course contentsShow
← Software Engineering
Lesson 852 of 1,93326. API Contracts and DocumentationFree lesson

Client Library Versioning

Coordinate versioning between server APIs and client SDKs to ensure compatible client-server communication.

Client Library Versioning

You'll learn how to coordinate versions between your server APIs and the client SDKs that consume them.

What Is Client Library Versioning?

When you publish client libraries (SDKs) that wrap your API, those libraries need their own version numbers separate from—but coordinated with—your API versions. Client library versioning is the practice of assigning versions to your generated or hand-written SDKs in a way that clearly communicates compatibility with specific API versions.

The Coordination Challenge

Think of it like a phone charger and phone: the charger (client library) must match the charging port (API version) on your device. If your API is at version 2.0 but your Python SDK still targets 1.0, developers will face cryptic failures or missing features.

The key is establishing a clear mapping:

  • API version 1.x → SDK version 1.y.z
  • API version 2.x → SDK version 2.y.z

The major version of your SDK typically matches the major version of the API it targets. Minor and patch versions handle SDK-specific improvements like better error messages, performance optimizations, or bug fixes that don't require API changes.

Version Communication

Your SDK documentation should explicitly state: "This SDK version 2.3.1 is compatible with API version 2.x." This transparency prevents developers from using mismatched versions that might appear to work but fail subtly.

When you release a breaking API change (say, moving from API v2 to v3), you publish a new major SDK version (SDK v3.0.0). You might maintain both SDK v2.x and v3.x simultaneously during your deprecation period, giving clients time to migrate.

Key Takeaway: Client library versions should track API versions to ensure developers always know which SDK works with which API, preventing integration failures and reducing support burden.