James Higginbotham (LaunchAny): AI-Assisted API Design and Documentation

This talk was presented at the AI The Docs 2025 online conference. We are thrilled to share the recording and the summary with you. 

Visit the talk summary page to see all of the presentations from the conference.

presentation

James Higginbotham (API coach, Founder of LaunchAny)

Summary

How can we effectively understand the problem, user needs, and business goals for an API before design, and how can AI assist in this critical initial stage (the Align phase)? 

In his talk, James Higginbotham (API coach, Founder of LaunchAny) explores how Generative AI (Gen AI) is transforming the ADDR process (Align, Define, Design, Refine) to improve API design and documentation. It highlights how AI assistance accelerates workflows, enriches context, and allows technical writers to focus on high-value contributions. 

ADDR Process and AI Impact 

1. Align Phase 

The Align phase prioritizes clear communication and understanding the API’s goals, ensuring alignment with business architecture and user outcomes. Using a “jobs to be done” approach, teams break down problems into job stories with defined situations, jobs, and desired outcomes. Gen AI supports this phase by generating initial job stories, asking clarifying questions, identifying gaps, and proposing unifying job stories. Even in unfamiliar domains, AI leverages available context to surface relevant questions, creating a rich environment for subsequent documentation efforts. 

2. Define Phase 

In the Define phase, insights from Align are translated into an abstract API profile, outlining ecosystem boundaries, compliance requirements, and core operations. Gen AI helps draft this profile, suggesting example fields, prompting for missing considerations, and accelerating preparation for design. This reduces manual effort while providing a robust foundation for the API’s structure. 

3. Design Phase 

The Design phase applies a chosen API style (e.g., REST, GraphQL, gRPC) to the API profile, adhering to a style guide. Gen AI can generate largely compliant OpenAPI 3.x specifications from a style guide prompt. While initial outputs may lack descriptive depth, AI can expand documentation, add examples, and clarify API behavior, making design outputs immediately more actionable. 

4. Refine Phase 

Refinement involves producing mocks, walkthroughs, and getting-started guides to gather feedback before production. Gen AI accelerates this phase by creating comprehensive documentation artifacts, including README files with HTTP request/response examples, SDK samples, Postman collections, and visual workflows via Mermaid diagrams. These artifacts facilitate rapid socialization, testing, and iterative feedback on the API design. 

Key Takeaways: 

• Gen AI transforms business requirements into rich context, giving technical writers a decisive advantage in API design and documentation.
• AI excels at generating synthetic or real-world examples, making APIs quickly understandable.
• Experimentation costs are dramatically reduced, enabling exploration of multiple design options that were previously impractical.
• AI is a tool, not the artisan: technical writers remain the subject matter experts who leverage AI to drive design, gather feedback, and ensure high-quality documentation. Early involvement (especially in the Align phase) is essential for effective outcomes.