API SDK, explained
SDKs handle authentication, retries, pagination and serialization so developers can call client.invoices.retrieve(id) instead of building HTTP requests. Many are generated from an OpenAPI description.
SDKs usually follow semantic versioning. A major SDK release can break consumer code even when the underlying HTTP API did not change.
Related terms
- Semantic versioning (SemVer): Semantic versioning is a MAJOR.MINOR.PATCH numbering scheme where a major bump signals a breaking change, a minor bump adds backward-compatible features, and a patch fixes bugs.
- OpenAPI Specification: The OpenAPI Specification is a standard, language-agnostic format (YAML or JSON) for describing HTTP APIs: their paths, operations, parameters, schemas and authentication.
- API versioning: API versioning is the practice of exposing multiple versions of an API at once so providers can ship breaking changes while existing clients keep using the version they were built for.