Frank Kilcommins (SmartBear): The API Workflows Specification – Unlocking API Value for Humans and Machines

In this presentation, Frank Kilcommins discusses a new initiative under the OpenAPI umbrella called the workflow specification. He explores its potential as the missing piece in the API puzzle to unlock value for both human and machine interactions with APIs. 

Key Takeaways 

Importance of Good API Documentation 

• Critical for Success: Proper API documentation is essential for cataloging, discovering, and adopting APIs. Poor documentation can hinder the success of API programs. 
• Technical References and More: While technical references are fundamental, comprehensive documentation should also include concepts, tasks, and scenarios to convey the business value effectively. 

Workflow Specification Overview 

• Purpose: The workflow specification aims to describe use case-oriented APIs in a programmatically readable format using JSON or YAML. It helps document a series of API calls needed to achieve specific business outcomes. 
• Human and AI Use Cases: Initially focused on human-oriented use cases, the specification has expanded to include AI use cases, supporting both API practitioners and AI consumers. 

Benefits of Workflow Specification 

• Deterministic API Use: Provides a clear, step-by-step recipe for using APIs, essential for both human and AI consumers to ensure correct and efficient usage. 
• Living Documentation: Ensures that documentation remains up-to-date with the actual API design and implementation, preventing it from becoming stale or out of sync. 
• Improved SDK and Code Generation: Generates focused SDKs and code for specific workflows, reducing boilerplate code and streamlining development. 

Ensuring Business Value 

• Validation and Monitoring: Allows for continuous validation of the business value exposed by APIs, ensuring that changes do not negatively impact the value delivered to consumers. 
• Security and Compliance: Helps monitor API consumption patterns to detect security risks and ensure compliance with regulatory requirements, such as open banking standards. 

Interoperability and Resilience 

• Industry-Agnostic Approach: The specification is designed to be vendor-neutral, promoting interoperability across different tools and platforms. 
• AI Integration: Facilitates the integration of AI models with APIs, ensuring they can understand and interact with APIs correctly without relying on specific implementations. 

Practical Example 

• Pet Adoption API: Frank provides a practical example involving a pet adoption workflow. He demonstrates how the workflow specification can define a series of steps to search for, initiate, and confirm the adoption of a pet using separate APIs. 
• Tooling and Human Readability: While the specification in YAML is suitable for AI, tooling built around the specification can convert it into more human-readable documentation, enhancing usability for developers. 

AI as a Productivity Tool 

• Emerging Capabilities: Discusses the notion of emergent abilities in AI models and the importance of viewing AI as a productivity tool that requires human oversight to ensure the accuracy and relevance of its outputs. 
• AI as an API Consumer: Highlights the challenges AI faces when consuming poorly documented APIs and the role of the workflow specification in mitigating these issues by providing clear, semantic instructions. 

Conclusion 

Frank’s presentation underscores the transformative potential of the workflow specification in improving API documentation and consumption. By bridging the gap between human and AI interactions with APIs, the specification promises to enhance developer productivity, ensure business value, and support the seamless integration of advanced AI technologies in the API ecosystem.