30. Pattern: Intent-Based Design

The Intent-Based Design pattern shifts the architectural focus of an interface away from exposing underlying data models (the “How”) and toward fulfilling the specific goals and outcomes of the consumer (the “Why”).

By encapsulating complex business logic, rule evaluations, and multi-step orchestrations behind a single atomic operation, this pattern drastically reduces the cognitive load on the client. It is particularly critical for enabling reliable AI-agent integrations, as it prevents probabilistic models from having to navigate fragile, multi-step deterministic data chains.

30.1. Overview

For the past two decades, API design has largely focused on a “data-first” mindset, moving structured JSON between systems and exposing data resources via standard CRUD operations. This approach forces the API consumer to act as the domain expert—requiring them to understand intricate status flags, retrieve contextual policies, and carefully orchestrate sequential HTTP calls to achieve a business outcome.

While human developers can write hardcoded scripts to navigate this complexity, autonomous AI agents struggle. When a probabilistic Large Language Model (LLM) is forced to manipulate data via multiple API calls, it risks failing mid-chain (e.g., canceling a flight but failing to book the replacement), leaving the system in an inconsistent state.

Intent-based design solves this by moving reasoning inside the API boundary. Instead of exposing database tables, the API exposes capabilities aligned to specific intents—such as Do, Know, Understand, Verify, Decide, or Watch. If an organization cannot rewrite legacy APIs, they can apply a Backend for Context (BFC) adapter pattern to shape, filter, and summarize data into intent-based interfaces for AI consumption.

30.2. When to Use Intent-Based Design

Use the Intent-Based Design pattern when:

  • Integrating APIs with AI agents and LLMs. Intent-based design minimizes inputs, maximizes output utility, and drastically reduces token consumption in an AI’s context window.

  • Encapsulating volatile business rules. When domain logic (e.g., return eligibility, promotional exceptions) changes frequently, centralizing this logic on the server prevents disparate clients from implementing conflicting rules.

  • Preventing mid-transaction failures. If a user objective requires mutating multiple resources simultaneously, an intent-based endpoint ensures the operation succeeds or fails as a single atomic transaction.

  • Serving diverse clients. Mobile apps, voice assistants, and AI agents all benefit from a unified endpoint that removes the burden of reimplementing complex orchestration.

30.3. When NOT to Use Intent-Based Design

Avoid the Intent-Based Design pattern when:

  • Providing raw data extracts for analytical processing. If the consumer is an ETL pipeline, data warehouse, or bulk backup system, a data-first approach (providing direct representation of state) is required.
  • Building generic data storage services. If your service is a literal database wrapper (e.g., a generic headless CMS, a cloud storage bucket), the intent is standard CRUD manipulation.

30.4. What the Pattern Looks Like

Below is a comparison of how a client executes a product return using a traditional Data-First API versus an Intent-Based API.

1. The Data-First Approach (Anti-Pattern for AI)

The client (or AI agent) must act as the domain expert, making seven sequential API calls and interpreting the raw data at every step.

  1. Check Order: GET /orders/{orderId} to ensure it is in a returnable status.

  2. Fetch Policy: GET /policies/returns?category=electronics to manually calculate if the purchase is within the return window.

  3. Check Item Eligibility: GET /products/{productId}/return-eligibility to ensure the specific item is not restricted.

  4. Check Refund Methods: GET /customers/{customerId}/payment-methods to reason which refund method is viable.

  5. Initiate Return: POST /return passing all prior decisions.

  6. Generate Label: POST /shipping/labels providing weights and carrier preferences.

  7. Update Order: PATCH /orders/{orderId} to close the loop and prevent a silent data integrity failure.

2. The Intent-Based Approach

The API consumer is freed from reasoning about business policies. The rules live once at the source, maintained by domain owners. The client makes a single atomic call declaring its intent.

Request

POST /product-returns HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "orderId": "ord_8821",
  "itemId": "prd_104",
  "reason": "defective"
}

Response

The API handles all seven steps internally and returns a fully realized outcome.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "eligible": true,
  "returnId": "RET-8821",
  "refundMethod": "original_payment",
  "refundEstimate": "$89.00",
  "refundTimeline": "3-5 business days",
  "labelUrl": "https://api.example.com/labels/1Z999AA1.pdf",
  "carrier": "UPS",
  "instructions": "Drop off at any UPS location by March 23rd."
}

30.5. Anti-Patterns to Avoid

  • Forcing API consumers to stitch data: Relying on the client to join data from multiple endpoints or filter out sensitive information leaks domain complexity and bloats AI context windows.

  • Exposing raw database flags: Returning obscure true/false flags or complex nested exception arrays forces the consumer to guess how to interpret the system’s state.

  • Chaining mutations for a single goal: Forcing an AI to independently cancel an old record and then create a new record in separate calls introduces massive risk if the agent fails mid-chain.

30.6. OpenAPI Example

An OpenAPI 3.0.3 specification illustrating an intent-based endpoint for changing a flight. Instead of fetching rules and chaining cancellations/bookings, the API exposes a single change-flight action.

openapi: 3.0.3
info:
  title: Airline Reservations - Intent-Based API
  version: 1.0.0
servers:
  - url: https://api.example.com

paths:
  /reservations/{reservationId}/change-flight:
    post:
      summary: Change an existing flight (Intent)
      description: Atomically evaluates fare rules, cancels the old flight leg, and books the new flight in a single transaction. 
      tags: [Reservations]
      parameters:
        - in: path
          name: reservationId
          required: true
          schema:
            type: string
            example: "RES-9921"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - newFlightId
              properties:
                newFlightId:
                  type: string
                  example: "FLT-884"
      responses:
        '200':
          description: Flight successfully changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightChangeOutcome'

components:
  schemas:
    FlightChangeOutcome:
      type: object
      properties:
        success:
          type: boolean
        newReservationId:
          type: string
        fareDifference:
          type: number
        paymentStatus:
          type: string
          example: "refunded_to_original_method"

30.7. Visualizing Intent-Based Design (Mermaid Diagram)

sequenceDiagram
    autonumber
    actor Client as AI Agent / Client App
    participant API as Intent-Based API (BFC)
    participant Core as Backend Services

    Note over Client,Core: Intent: "Change my flight"
    Client->>API: POST /reservations/RES-123/change-flight (newFlightId)
    
    Note right of API: API Server assumes cognitive load
    API->>Core: 1. Validate rules & fare differences
    API->>Core: 2. Lock current reservation
    API->>Core: 3. Cancel old flight
    API->>Core: 4. Book new flight
    API->>Core: 5. Process refund / charge
    
    Core-->>API: Transaction Complete
    API-->>Client: 200 OK (Outcome: Success, Fare Difference, New Itinerary)
    Note over Client: Agent achieves goal with zero mid-chain risk<br/>and minimal context window usage.