It’s exciting to see how rapidly the world of API design and development is evolving. At apidays New York 2025, I shared an approach I call AI + ALPS = API, which I believe can fundamentally change how we go from a simple API story to a functional prototype. My talk dives into how generative AI (GenAI), combined with the power of the ALPS specification, can help us achieve this with minimal effort and technical overhead.
This article, which distils my process, aims to explain the core concepts behind ALPS (Application Level Profile Semantics), the power of API stories, and how GenAI can be leveraged to automate API design and implementation. Whether you’re an API architect, developer, product manager, or just an enthusiast, I hope this exploration offers you practical insights on accelerating API prototyping using AI-driven workflows.
Understanding ALPS: The Foundation for Generic API Descriptions
Before we get into the nitty-gritty of AI-powered API creation, it’s crucial to understand ALPS. ALPS, or Application Level Profile Semantics, is a specification designed to provide a fully descriptive, single-document format that can describe interfaces across various protocols. This isn’t just about RESTful APIs; it includes asynchronous APIs, RPCs, and other styles.
I started this as an experiment over a decade ago, and it was first introduced at RESTFest in 2011, though its conceptual roots go back to an XML metadata profile from 2003. This long history highlights its robust conceptual foundation. The goal of ALPS is to clarify the application-level meaning and structure of interfaces in a generic, protocol-agnostic way.
Unlike more widely known interface description languages like OpenAPI, which are tightly coupled with REST and HTTP, ALPS offers much greater flexibility and generality. This makes it particularly well-suited for today’s diverse API ecosystems, especially the growing bot and AI-driven environments.
One of the reasons ALPS remains so compelling today is its utility in the age of chatbots and AI assistants, where detailed application description documents are invaluable. While there are multiple tools around ALPS—like an online editor similar to SwaggerHub, command-line utilities for authoring and validation, and even an ALPS assistant powered by OpenAI—the specification remains underutilized and less known in the broader API community.
All these ALPS tools were created by Akihito Koriyama and his organization in Japan, who have successfully integrated ALPS into their application design and development workflow. Koriyama’s work also includes significant contributions to API architecture and REST, notably through his PHP framework called Bare Sunday.
Akihito Koriyama once said, “Business requirements have been interpreted and formalized by engineers, and I want to close the gap.” This quote perfectly encapsulates a crucial challenge in API design: bridging the divide between business intent and technical implementation. ALPS, especially when combined with AI, offers a promising path to narrowing this gap by enabling clearer, more accessible API descriptions that anyone in an organization can understand and contribute to.
The Power of API Stories: Starting with Shared Understanding
For me, every great API begins with a story. APIs are essentially solutions to real-world problems or feature requests, and articulating them as stories forms the foundation for shared understanding among all stakeholders. These stories capture why an API is needed and what it should do.
Our brains are wired for stories, not raw data. Stories are accessible, repeatable, and easy to communicate. Whether you’re in an elevator pitch or a team meeting, you can succinctly describe what you’re working on as a story. For example:
- “We’re building a person API to keep track of people important to us.”
- “We’re updating the customer service system to improve follow-up.”
This narrative approach makes API design inclusive, enabling domain experts, engineers, executives, and new team members to collaborate effectively without getting bogged down by technical jargon.
I often share a practical example of an API story I used to design a task management system. The story outlines the need to track task records to improve timeliness and accuracy in customer follow-ups. It lists all necessary data elements and possible actions such as listing, creating, updating, and marking tasks complete—all captured in a single-page plain text document.
Noticeably absent are any references to technical details like HTTP methods, URLs, or protocols. This simplicity is intentional. It ensures the story is accessible and editable by anyone, fostering collaboration and iterative refinement.
A more distilled version of the story might read:
As a product manager, I need a task tracking system. These tasks have the following data elements. Users should be able to perform the following actions, including filtering services.
Such stories are the bread and butter of API design, setting the stage for the next steps in the process.
From API Story to ALPS Document: Using GenAI to Generate API Descriptions
Once we have the API story, the next step is to convert it into a formal API description document—specifically, an ALPS profile. This is where generative AI truly shines. I demonstrate how GenAI can automate this transformation using carefully crafted prompts.
I use a prompt library designed specifically for working with ALPS. I feed the story into a chatbot along with detailed instructions on how to generate the ALPS document. Think of this prompt as a teacher guiding the AI step-by-step through the process of authoring the profile.
The AI then generates a complete ALPS document that describes the API’s resources, actions, and data structures. This document can also be converted into other formats like OpenAPI if needed, offering flexibility in how the API is documented and consumed.
Once generated, the ALPS document is validated using an online editor that visually represents the API structure, showing objects, actions, and relationships. This validation step is crucial to ensure the description is correct and ready for use in the next phase.
While I often skip the live validation in my talks due to time constraints, I always emphasize that this step is included in the shared repository and is vital for maintaining the integrity of the API description.
From ALPS to Working Code: Generating a Node.js API Prototype
Describing the API is only half the battle; the real challenge is implementation. I illustrate how the ALPS document, combined with additional prompt instructions, can be used by GenAI to generate a working Node.js API prototype.
The ALPS document acts as a map or blueprint, guiding the AI in creating an Express.js service that supports the defined resources and actions. This prototype is minimalist and proof-of-concept level—designed for testing ideas quickly rather than for production deployment.
A key insight I’ve learned is the importance of including all necessary prompt materials each time the AI is engaged. Because AI models do not have persistent memory between sessions, providing the ALPS document alongside the instructions ensures consistent, well-informed output.
Watching the code generate character by character is not just entertaining; it also provides transparency into the AI’s process and helps catch issues early.
Once generated, I test the API by accessing endpoints such as /101 to retrieve task records and /users to manage user data. The API is functional, demonstrating that in just minutes, we can go from a textual story to a live mock server.
Benefits and Practical Uses of This AI-Driven API Prototyping Workflow
This approach offers several significant advantages for API teams and organizations:
- Rapid prototyping: Quickly turn ideas and user stories into working APIs for validation and demonstration.
- Collaborative design: Use plain-text stories to involve non-technical stakeholders early in the design process.
- Iterative development: Easily modify stories, regenerate ALPS documents, and update working prototypes in minutes.
- Tooling integration: Leverage ALPS editors, command-line tools, and AI assistants to automate and validate API designs.
- Flexibility: ALPS’s generic format supports multiple API styles beyond REST, including async APIs and RPC.
I always emphasize that while this method is excellent for prototyping and experimentation, it is not intended to replace traditional development practices for production-quality code.
Understanding the Limits: Prototyping vs. Production Code
It’s absolutely crucial to distinguish between generating quick prototypes and building production-ready applications. I often reference the concept of vibe coding, a phrase coined by Andrej Karpathy, which involves accepting whatever the AI produces and moving forward without much refinement.
Karpathy himself found that while AI can generate code quickly, the output is often messy and unsuitable for critical applications. As he put it, “Basically, it’s messy and not a good idea for anything of actual importance.” This reinforces the idea that AI-driven coding is best suited for exploration and mockups rather than mission-critical software.
Therefore, the workflow I present is a powerful way to accelerate the early stages of API design and validation, but developers should still apply rigorous engineering practices for production deployments.
Getting Started: Resources and Next Steps
I’ve made all the materials from this process available in a public repository, complete with walkthrough instructions. This includes:
- Prompt libraries for generating ALPS documents from API stories.
- Tools and instructions for validating ALPS profiles.
- Templates and prompts for generating Node.js API code from ALPS documents.
These resources can serve as a foundation for teams looking to create their own custom generator processes that turn textual API stories into formal descriptions and eventually into functioning code.
For those interested in exploring the ALPS specification further, there is ample online documentation and tooling to support learning and experimentation.
Embracing the Future of API Design with AI and ALPS
My presentation at Apidays New York 2025 offers an exciting glimpse into the future of API design, where human creativity and AI capabilities combine to streamline workflows. By starting with simple, accessible API stories and leveraging ALPS as a generic, flexible interface description language, teams can rapidly prototype APIs using generative AI tools.
This approach not only accelerates development but also fosters collaboration across technical and non-technical stakeholders by grounding design in shared stories rather than complex technical specifications. While not a replacement for production engineering, this method is a valuable addition to any API team’s toolkit—especially for early-stage validation, experimentation, and education.
As the landscape of API development continues to evolve, embracing tools like ALPS and AI-driven generation will become increasingly important for staying agile and responsive to business needs. My work exemplifies how thoughtful integration of these technologies can close the gap between business intent and technical realization, ultimately leading to better-designed APIs and more effective digital products.
Thank you for exploring this journey from API story to working prototype. I hope it inspires you to experiment with AI and ALPS in your own API projects and to share your discoveries with the broader community.
