# Designing REST APIs for the age of AI agents - Boyan Mihaylov - NDC Copenhagen 2026

## Executive summary

The talk argues that REST APIs, originally designed for human developers, must fundamentally adapt to serve AI agents and LLMs as primary consumers. To ensure reliability and discoverability in an AI-driven world, API designers must focus on structured documentation (OpenAPI), robust error handling, maintaining consistency, implementing adaptive rate limiting, and considering new standards like the Model Context Protocol (MCP) for web integration.

## Key takeaways

- AI Agents are a New Consumer: The rise of AI tools means that API consumers are shifting from human developers to autonomous agents. These agents will interact with APIs by generating requests and chaining calls, requiring the API to be machine-readable and reliable.
- Documentation is Critical for AI: The OpenAPI standard (JSON or YAML specification) is crucial. Beyond simply documenting endpoints, developers must add rich metadata about the API's purpose, constraints, and potential errors to minimize agent hallucination.
- Prioritize Error Handling: Instead of basic validation messages, provide detailed error information (e.g., specifying the problematic field and supported options) to allow AI agents to self-correct and retry requests effectively.
- Adopt Adaptive Rate Limiting: Traditional static rate limiting (e.g., fixed quotas per minute) is insufficient for unpredictable AI agent traffic. Implement adaptive strategies that analyze traffic patterns and adjust limits dynamically to maintain service availability.
- Consider Web MCP: For web-based services, the Model Context Protocol (MCP) is an emerging standard allowing a webpage itself to expose tools and workflows directly to AI agents, making the entire page functional rather than just relying on backend APIs.

## Technical details

- API Evolution (REST vs. SOAP): The shift from XML-based protocols like SOAP to JSON/JavaScript-friendly REST APIs was driven by the need for easier data handling in dynamic web browsers.
- OpenAPI Specification: This is the standard JSON or YAML format used to define a web service's capabilities, including endpoints, required inputs (schemas), and expected outputs. It is essential for machine understanding.
- Idempotency: Operations must be designed to be repeatable without causing unintended side effects (e.g., ensuring a banking deposit executes only once), which is critical given the unpredictable nature of AI agent retries.
- Rate Limiting Best Practices: When implementing rate limiting, always return HTTP status code 429 (Too Many Requests) and include a `Retry-After` header to guide the client on when it can safely retry.
- Workflow vs. Endpoints: Instead of exposing independent endpoints, structure APIs to provide a clear workflow or sequence of actions (e.g., 'get coffee' -> 'order coffee'). This is more efficient for agents than simple web scraping.

## Practical implications

- Treat API documentation not just as a reference for humans, but as a core component of the product that must be machine-readable and comprehensive.
- Implement detailed error schemas to guide AI agents through failure states, reducing reliance on manual debugging.
- Architect APIs with clear workflows (sequences of calls) rather than treating every endpoint as an isolated function.
- Audit API quality metrics (including documentation and security) and make them a primary OKR for the product team.

## Topics

REST API Design, AI Agents/LLMs, API Documentation (OpenAPI), Error Handling, Rate Limiting, Web Protocols (MCP), OpenAPI Specification, GraphQL, Model Context Protocol (MCP)

Source: https://www.youtube.com/watch?v=FlAJJr7LfU8