Building Natural Language Interfaces with Large Language Models and OpenAPI Specs
This article explores how Spotify leveraged Large Language Models (LLMs) and OpenAPI specifications to create a natural language interface for their Ads API. It details the architecture and process of transforming API definitions into a conversational tool, highlighting the implications for API design, developer experience, and system integration without requiring extensive compiled code.
Read original on Spotify EngineeringThe article discusses Spotify's approach to building a natural language interface (NLI) for their Ads API. This involves using Large Language Models (LLMs), specifically Claude Code Plugins, to interpret user queries and translate them into API calls. This architectural pattern significantly enhances developer experience by abstracting away the complexities of direct API interaction, enabling a more intuitive way to manage ad campaigns.
Leveraging OpenAPI for LLM Integration
A core architectural decision was to utilize OpenAPI specifications. These machine-readable descriptions of APIs provide the LLM with the necessary context about available endpoints, parameters, and expected responses. This approach reduces the need for manual prompt engineering and allows the LLM to dynamically understand and interact with the API based on its documented structure. This highlights the importance of well-defined and standardized API documentation in modern system design, especially when integrating with AI components.
API Design Best Practice
Designing APIs with clear, consistent OpenAPI specifications is crucial not only for human developers but also for seamless integration with AI agents. A robust OpenAPI definition serves as a universal contract for interaction.
Architectural Flow
- User Input: A user provides a natural language query (e.g., "Show me my ad campaigns for Q3").
- LLM Interpretation: The LLM (Claude Code Plugin) receives the query and, using the provided OpenAPI schema, identifies the relevant API endpoint and constructs the necessary parameters.
- API Call Generation: The LLM generates the code/request to call the Spotify Ads API.
- API Execution: The generated API call is executed against the Spotify Ads API.
- Response Processing: The API response is returned to the LLM, which then processes it and presents the information back to the user in a human-readable format.
This pattern allows for rapid iteration and extension of the natural language interface without requiring changes to the underlying compiled code. The system's intelligence is derived from the LLM's ability to interpret, generate, and execute actions based on structured API metadata, demonstrating a powerful paradigm for API interaction and automation in distributed systems.
Trade-offs and Considerations
While powerful, this approach introduces considerations such as the LLM's accuracy in interpreting complex queries, potential latency in generating and executing API calls, and security implications of granting an LLM access to execute API operations. Robust error handling, logging, and access control mechanisms are essential system design components for such an interface.