December 2025 Summaries

Creating APIs and SDKs that don't break requires careful consideration of API versioning and understanding the complexities of how changes can affect users. APIs are essentially contracts, and breaking them can have significant consequences, especially when dealing with diverse and numerous clients who may rely on specific behaviors, even if unintentional. Versioning is critical, whether through explicit paths, headers, or other means, as it offers a structured way to manage changes without disrupting existing users. The challenge lies in balancing the need for innovation and improvements with the responsibility of maintaining backward compatibility. To mitigate potential breakages, strategies such as implementing feature flags, maintaining a stable core, and thorough testing are essential. Embracing these strategies and recognizing the implications of Hyrum’s Law, which suggests that users will depend on all observable behaviors, can help developers manage API evolution more effectively. Tools like Speakeasy provide support for creating resilient SDKs, emphasizing the importance of versioning and continuous testing to ensure seamless API integration and evolution.

Speakeasy has introduced a feature called "persistent edits," which allows developers to make and maintain arbitrary changes to generated SDKs and Terraform providers from OpenAPI specifications. This feature addresses the limitations of the previous approach, where the code generator owned the generated files, requiring users to either wait for new configuration options or manage changes separately. Persistent edits enable users to add utility methods, modify configuration files, and extend SDK initialization directly within the generated code, with changes persisting across regenerations unless they conflict with Speakeasy's updates. This is achieved through a conflict detection system similar to git merge, allowing seamless coexistence of user and system updates. The feature is available to all Speakeasy users and requires simple configuration adjustments to enable it, ensuring that generated code becomes a flexible foundation rather than a restrictive black box.

At Speakeasy, the need to process thousands of OpenAPI specifications daily led to the creation of a custom high-performance OpenAPI parser in Go, designed to address limitations in existing libraries. The newly introduced library, github.com/speakeasy-api/openapi, offers precise modeling of the specification and high-performance capabilities for reading, validating, mutating, and transforming specs at scale, handling complex aspects such as dynamic types and reference resolution in OpenAPI documents. Utilizing a reflection-based marshaller, the library supports multiple OpenAPI versions, Swagger, Arazzo, and Overlays, emphasizing correctness and developer experience. It features a "Porcelain vs. Plumbing" design for optimized internal performance while providing a clean API, and accommodates reference resolution, validation, and complex spec handling with a unified ecosystem approach. Additionally, the library includes a comprehensive CLI tool that mirrors its core capabilities, facilitating tasks like bundling, inlining, and sanitizing specs, and ensuring seamless integration into Go programs or CI pipelines.

Large infrastructure companies often face challenges managing multiple APIs under a single platform, as each API may require its own endpoint and credentials. Traditionally, Terraform's configuration model only offered global provider settings and individual resource settings, necessitating the creation of separate providers or custom code to handle complexities. However, with the introduction of per-resource security and server URLs in Terraform provider generation, users can now configure resource groups with their own endpoints and credentials within a single provider. This feature, which leverages the OpenAPI specification's operation-level security and server definitions, simplifies Terraform configurations by eliminating the need for multiple providers and complex codebases. It is especially beneficial for architectural patterns that separate control and data plane APIs, such as admin and data APIs, multi-tenant infrastructures, cluster-based systems, and database platforms. This new approach allows users to manage resources with distinct endpoints and authentication requirements more efficiently, reducing the complexity typically associated with managing multiple Terraform providers.

Migrating an existing Terraform provider to a code generation model poses challenges due to divergences between the provider's user-friendly interface and its underlying API structure. These differences often arise from efforts to enhance the user experience, such as simplifying data representations or improving field naming conventions. Speakeasy addresses these challenges by enabling data transformations through JQ expressions, which allow for the conversion between the provider’s interface and the API’s structure while maintaining the original user experience. This transformation layer facilitates both request and response translations, ensuring seamless integration and backward compatibility during migration. Additionally, Speakeasy offers a JQ playground to aid in the development and testing of these transformations, allowing providers to anticipate and adapt to future API changes without disrupting user workflows. The approach is valuable for retaining interface consistency, improving user experience, and preparing for planned API modifications, though it is advised to use transformations judiciously to avoid unnecessary complexity.

SDKs, especially when integrated with evolving APIs, can present challenges such as receiving a 200 response from the server alongside an SDK error due to strict validation practices. This often occurs due to API changes like new enum values or missing fields, which can cause SDKs to reject responses despite successful server processing. To address these issues, Speakeasy SDKs offer client-side solutions that maintain functionality amidst API evolution without compromising type safety or developer experience. These include forward-compatible enums and unions, lax mode for handling missing fields, and smart union deserialization for better type discrimination. While server-side solutions like tagging API versions and contract testing can mitigate such issues, they might not be feasible for all API providers, making client-side adaptability crucial. The features of Speakeasy SDKs are tailored to TypeScript but similar behaviors are implemented across other languages, ensuring a robust developer experience as APIs grow and change.