Nolan Di Mare Sullivan (Speakeasy): Get Your OpenAPI Spec Ready For Code Generation

Nolan Di Mare Sullivan's presentation focused on optimizing Open API specifications for code generation and improving API accessibility, particularly with regard to AI. He emphasized the importance of making APIs easy to understand and integrate with by adhering to best practices in API design, which not only enhances code generation but also benefits AI tools that interact with APIs. 

Key Takeaways 

• Importance of SDKs and Code Generation 
  • Definition and Benefits: SDKs (Software Development Kits) are crucial for improving the time-to-production for users of an API. They simplify the integration process, reduce support complexity, and ultimately lead to happier users and increased revenue. 
  • AI Integration: High-quality Open API specs enhance the ability of AI tools to understand and interact with APIs, as well-crafted specs lead to better code generation and usability. 
• Optimizing Open API Specs for Code Generation 
  • Operation IDs: Use descriptive and human-readable operation IDs. Consistent and straightforward naming helps ensure that generated code is understandable and maintainable. 
  • Component Schemas: Implement component schemas to manage reusable components efficiently. This practice helps maintain consistency and simplifies updates across multiple endpoints. 
  • Tags: Utilize tags to group related operations logically. This improves the organization of the API and makes it easier for users to understand and navigate the generated client libraries. 
  • Error Codes: Clearly define and include error responses in the spec. Properly handled error codes are crucial for user experience, providing meaningful feedback during failures. 
  • Avoid 'anyOf': Use the 'oneOf' keyword instead of 'anyOf' to avoid issues with combinatorial generation of object types. This approach is more compatible with most code generation tools. 
• Overcoming Organizational Pitfalls 
  • Spec Maintenance: Begin with a basic spec and iteratively improve it. Whether maintaining it by hand or generating it, it's better to have a spec that is not perfect than none at all. 
  • Governance Workflows: Establish governance workflows to ensure spec quality before scaling up to code generation. Demonstrating value with high-quality endpoints can help in gaining organizational support. 
• Resources and Tools 
  • Open API Reference: Nolan highlighted a newly developed Open API reference, which provides practical advice on spec design and includes an AI-driven tool for querying Open API questions. 
  • Speak Easy and Other Tools: He recommended Speak Easy for enterprise-level code generation, but acknowledged that various open-source tools are available for different needs. 

Nolan concluded by encouraging the audience to explore and apply these best practices to enhance their API specifications, resulting in better integration experiences and improved support for both human and AI users.