Skip to content

OpenAPI Interoperability

Jump to bottom
TamTunnel edited this page Dec 2, 2025 · 1 revision

OpenAPI Interoperability

AWAS v1.1 provides optional OpenAPI integration to leverage existing API documentation and tooling while maintaining AWAS as the source of truth for AI agent interactions.

Overview

OpenAPI (formerly Swagger) is the industry standard for describing RESTful APIs. Most web and cloud developers are already familiar with OpenAPI's format and tooling. By supporting OpenAPI references in AWAS manifests, we:

  • Reduce cognitive load: Developers can work with familiar tools and formats
  • Avoid duplication: Reference existing OpenAPI specs instead of rewriting schemas
  • Maintain compatibility: Keep AWAS as the authoritative specification while enabling OpenAPI tooling
  • Enable gradual adoption: Sites with OpenAPI can add AWAS incrementally

Design Principles

  1. AWAS is Authoritative: If there's any conflict between AWAS manifest and OpenAPI spec, AWAS semantics take precedence for agent behavior
  2. Optional Enhancement: OpenAPI fields are entirely optional; agents that don't support OpenAPI simply ignore them
  3. Vendor Neutral: Not tied to any specific API platform or vendor (OpenAI, Google, Anthropic, etc.)
  4. Backward Compatible: Existing manifests without OpenAPI references continue to work unchanged

OpenAPI Object Structure

Within any action definition, you can add an optional openapi field:

{
  "openapi": {
    "documentUrl": "/openapi.json",
    "operationId": "searchProducts",
    "$ref": "#/paths/~1api~1search/get"
  }
}

Fields

  • documentUrl (string, optional): URL to the OpenAPI document (JSON or YAML)

    • Can be absolute: https://api.example.com/v3/openapi.yaml
    • Or site-relative: /openapi.json

  • operationId (string, optional): The operationId from the OpenAPI document that corresponds to this AWAS action

    • Recommended approach for clean references
    • Example: "searchProducts"

  • $ref (string, optional): JSON Pointer to the specific operation in the OpenAPI document

    • Use when you don't have or don't want to rely on operationId
    • Example: "#/paths/~1api~1search/get"
    • Note: / must be escaped as ~1 in JSON Pointers

Usage Guidelines

When to Use Each Field

Use documentUrl + operationId (recommended):

"openapi": {
  "documentUrl": "/openapi.json",
  "operationId": "searchProducts"
}

Use documentUrl + $ref when referencing by path:

"openapi": {
  "documentUrl": "/openapi.json",
  "$ref": "#/paths/~1api~1products~1search/get"
}

Use all three for maximum compatibility:

"openapi": {
  "documentUrl": "/openapi.json",
  "operationId": "searchProducts",
  "$ref": "#/paths/~1api~1products~1search/get"
}

Best Practices

  1. Ensure consistency: HTTP method and endpoint in AWAS MUST match the OpenAPI operation
  2. Include AWAS schemas: Use inputSchema and outputSchema in AWAS even when linking to OpenAPI for faster agent parsing
  3. Keep synchronized: When updating APIs, update both OpenAPI spec and AWAS manifest
  4. Document AWAS-specific semantics: Use AWAS fields like sideEffect, intent, preconditions for behavior that isn't captured in OpenAPI

Complete Example

Here's a full AWAS action with OpenAPI integration:

{
  "id": "search_products",
  "type": "search",
  "name": "Search Products",
  "description": "Search for products by keyword, category, or filters",
  "method": "GET",
  "endpoint": "/api/v1/products/search",
  "intent": "read",
  "sideEffect": "safe",
  "conformanceLevel": "L1",
  "openapi": {
    "documentUrl": "/openapi.json",
    "operationId": "searchProducts",
    "$ref": "#/paths/~1api~1v1~1products~1search/get"
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "q": {
        "type": "string",
        "description": "Search query string",
        "examples": ["laptop", "wireless mouse"]
      },
      "category": {
        "type": "string",
        "enum": ["electronics", "clothing", "books"],
        "examples": ["electronics"]
      }
    },
    "required": ["q"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "results": {
        "type": "array",
        "items": {"type": "object"}
      },
      "total": {"type": "integer"}
    }
  }
}

Agent Behavior

What Agents MAY Do

Agents that support OpenAPI interoperability may:

  • Fetch the OpenAPI document for additional context
  • Use OpenAPI schemas for enhanced validation
  • Generate code or SDK calls based on OpenAPI specs
  • Provide richer documentation to users
  • Use OpenAPI tooling for testing and mocking

What Agents MUST Do

All agents must:

  • Treat OpenAPI references as optional hints, not requirements
  • Fall back gracefully if OpenAPI document is unavailable
  • Respect AWAS manifest as the primary source of truth
  • Never require OpenAPI support for basic functionality
  • Handle cases where OpenAPI and AWAS conflict (AWAS wins)

Implementation Notes

For Site Owners

  1. Start with AWAS: Define your actions in AWAS first
  2. Add OpenAPI links: Reference existing OpenAPI operations
  3. Keep them synchronized: Update both when API changes
  4. Test independently: Ensure AWAS works even if OpenAPI is unavailable

For Agent Developers

  1. Make it optional: Don't require OpenAPI support
  2. Cache OpenAPI docs: Fetch once and reuse
  3. Validate cautiously: Use OpenAPI for hints, not enforcement
  4. Prefer AWAS: When in doubt, trust the AWAS manifest

FAQ

Q: Do I need OpenAPI to use AWAS? A: No. OpenAPI integration is completely optional.

Q: What happens if my OpenAPI spec and AWAS manifest disagree? A: AWAS manifest is authoritative. Agents should follow AWAS semantics.

Q: Can I use AWAS without creating an OpenAPI spec? A: Yes. AWAS is fully self-contained.

Q: Should I convert my OpenAPI spec to AWAS? A: Not necessarily. AWAS complements OpenAPI by adding AI-specific semantics like intents, side effects, and preconditions.

See Also

Clone this wiki locally