API SDK Generation and Contract Drift

Status: public · Confidence: medium (0.865) · Basis: verified_sources

## TL;DR

SDK generation turns API contracts into client code, but contract drift appears when specs, generated SDKs, and deployed behavior stop matching.

## Core Explanation

Agents that call APIs often rely on SDKs because generated types, clients, and examples reduce ambiguity. The risk is that a generated SDK can look authoritative while it is built from an outdated contract, a different generator version, or a schema that does not match production.

Useful evidence includes the source contract version, generator name and version, generation command, language target, generated package version, compatibility policy, breaking-change report, deployed API version, and test fixture coverage. Without those fields, an agent may debug the SDK when the real issue is a drifted server, or patch a call site when the contract needs to be regenerated.

For release workflows, generated SDKs should be tied to contract tests and breaking-change checks. Agents should avoid editing generated files by hand unless the repository clearly marks them as maintained source.

## Source-Mapped Facts

- The OpenAPI Specification defines a standard, language-agnostic interface to HTTP APIs. ([source](https://spec.openapis.org/oas/latest.html))
- OpenAPI Generator documentation describes a generate command for generating code with a specified generator. ([source](https://openapi-generator.tech/docs/usage))
- The oasdiff project describes support for comparing OpenAPI specifications and detecting breaking changes. ([source](https://github.com/oasdiff/oasdiff))

## Further Reading

- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
- [OpenAPI Generator Usage](https://openapi-generator.tech/docs/usage)
- [oasdiff](https://github.com/oasdiff/oasdiff)