OpenAI DevDay 2024 | Community Spotlight | Stainless

Summary

In this conversation, the speaker discusses the complexities of generating SDKs and APIs, focusing on the advantages of custom SDKs over open-source tools. They explain how their company overcame limitations with open-source generators, like OpenAPI Generator, by incorporating features like streaming support and custom code modifications. The discussion touches on API abstraction levels, the challenges of balancing simplicity and functionality, and the importance of keeping code 'pythonic' in languages like Python. The speaker also highlights the need for features like pagination and auto-retries, while emphasizing the necessity of exposing certain API details like headers.

Takeaways

• 😀 Custom SDK generation offers more flexibility than open-source tools like OpenAPI Generator, particularly with features such as streaming support and the ability to customize SDKs with arbitrary code.
• 😀 Open-source tools can be limiting when dealing with specific features, like streaming, which are not always well-supported or easy to integrate.
• 😀 The ability to add custom code to generated SDKs makes it possible to tailor them for specific use cases, such as integrating libraries like Zod and Pantic for structured outputs.
• 😀 SDK design depends on the level of abstraction required by the API; thin wrappers allow users to directly map the API’s behavior to the SDK, while abstractions may simplify usage but introduce additional learning curves.
• 😀 Avoiding abstractions that oversimplify API features is critical to prevent confusion, such as using different names for the same API feature.
• 😀 Pagination and auto-retries are useful abstractions in SDKs, as they address common API limitations like splitting large datasets or handling intermittent connectivity issues.
• 😀 Certain HTTP details, such as headers and response times, must be accessible through SDKs, even when abstractions are applied, to ensure proper logging and response handling.
• 😀 Auto-generated SDK code can sometimes be subpar, particularly in languages like Python, where there are specific conventions (e.g., 'pythonic' code) that need to be followed.
• 😀 For APIs that require full support for all their features, a thin layer over the HTTP request-response cycle is preferred, ensuring that all functionality is mapped to the SDK without imposing additional abstractions.
• 😀 SDK customization involves techniques like 'git cherry-picking' and patching to apply custom features while maintaining the original SDK's structure, making it easier to manage updates and changes.

Q & A

Why might someone choose a proprietary SDK generation service over open-source tools like OpenAPI Generator?

Proprietary SDK generation services offer additional features that open-source tools might lack, such as support for advanced use cases like streaming, custom code integration, and easier patch management. These services can also ensure that generated code adheres to language-specific best practices and provide higher-level abstractions like auto retries and pagination.

What was the main limitation of using OpenAPI Generator for SDK generation in the past?

OpenAPI Generator lacked support for streaming, which was a critical feature for certain use cases. This limitation led to the need for proprietary solutions that could handle more complex requirements.

What role does custom code play in SDK generation?

Custom code allows users to make arbitrary modifications to the SDKs, adapting them to specific requirements or business logic. This could include integrating libraries or making changes to how the SDK interacts with APIs.

How does the custom code integration process work in the proprietary SDK generation system?

The custom code is integrated through a process similar to applying a patch. Changes are made in separate branches, and relevant updates (like new types) are merged into the SDK via pull requests, making it easy to track and manage customizations.

What is the main advantage of using a thin wrapper over an API in SDK design?

A thin wrapper allows the SDK to closely mirror the underlying API, making it easier for users to map the functionality from the API documentation to the SDK. This approach is especially useful when the goal is to support the entire API without adding unnecessary complexity.

What are some common abstractions that SDKs handle effectively?

SDKs often handle abstractions like pagination, where data is split across multiple responses, and automatic retries, which help applications continue functioning in the event of transient errors (e.g., network failures). These abstractions save developers time and reduce error handling complexity.

Why is it important to expose certain HTTP details in an SDK?

Exposing HTTP details, such as headers or response times, is important because developers may need access to this information for logging, debugging, or customization. Hiding these details can make it harder for developers to troubleshoot issues or control how responses are processed.

What is the primary concern when generating SDKs using open-source tools like OpenAPI Generator?

The primary concern with open-source tools is that the generated code may not meet the quality standards expected in certain programming languages, such as Python, where code should adhere to 'Pythonic' conventions. Poorly generated code can be difficult to maintain or extend.

How do pagination and retries improve the SDK user experience?

Pagination helps manage large datasets by breaking them into smaller chunks, while retries ensure that temporary issues (e.g., network errors) don't cause failures. Both features provide a smoother experience, ensuring that applications can handle large responses and recover from errors automatically.

How do SDKs balance between providing too much abstraction and not enough?

SDKs should abstract away complex, repetitive tasks like managing retries and pagination, but they must also expose enough of the raw API details (like headers) to give developers control and insight into the interaction with the API. Striking this balance is crucial for usability and flexibility.