apilabs.ai API Contract DSL

for optimized API MCP testing with AI

Overview

The apilabs.ai API Contract DSL is an AI-native specification format designed to define APIs, authentication, models, requests, responses, and tests in a single developer-friendly YAML file for optimized AI testing in IDEs like Cursor™, Windsurf™, Codex™, and VS Code™.

Purpose

Unlike traditional API specifications that primarily focus on documentation and SDK generation, the apilabs.ai DSL is built for:

◆ AI-powered API testing
◆ Agentic API execution
◆ Workflow automation
◆ Secure secret management
◆ Git-native APIOps
◆ Public and private API execution
◆ Localhost and VPN-based API testing via Secure Tunnel

The DSL acts as a unified operational contract between developers, AI agents, API testing systems, workflow engines, observability platforms, and AI IDE integrations. Using this contract, apilabs.ai can automatically execute APIs, generate edge-case tests, validate schemas, detect failures, resolve secrets securely, and run workflows across public and private infrastructure.

Philosophy

Traditional API specifications were built primarily for documentation. The apilabs.ai DSL is designed for the AI era.

Instead of treating APIs as static endpoints, the DSL treats APIs as executable operational systems that AI agents can understand, execute, test, validate, observe, and automate.

Core Principles

- APIs should be executable, not just documented
- AI agents should safely interact with APIs
- Secrets should never live in Git
- Contracts should be readable by both humans and AI
- Testing should be embedded directly into the contract
- Public and private APIs should work uniformly
- Infrastructure complexity should be abstracted away from developers

Design Goals

The DSL is intentionally:

- Minimal
- Git-friendly
- AI-readable
- Environment-aware
- Secure-by-default
- Extensible for future AI workflows

AI-Native APIOps

The apilabs.ai DSL serves as the foundation for AI-native APIOps inside Cursor, Windsurf, Codex, VS Code, and future AI IDEs and agent runtimes — through apilabs.ai.

Example: Orders API

name: Orders API
version: 1.0
base_url: "{{baseUrl}}"

environments:
  dev:
    base_url: http://localhost:3000
  prod:
    base_url: https://api.example.com

auth:
  type: bearer
  apilabs_auth_mgr_ARN: aws-sm://orders/prod/access-token

models:
  CreateOrderRequest:
    customer_id: string
    amount: number
    currency: string
    description: string
    metadata: object
  CreateOrderResponse:
    id: string
    status: string
    amount: number
    currency: string
  ErrorResponse:
    error: string
    message: string

routes:
  - id: create_order
    name: Create Order
    method: POST
    path: /orders
    description: Create a new customer order.
    models_ref:
      request: CreateOrderRequest
      response:
        201: CreateOrderResponse
        400: ErrorResponse
    request:
      headers:
        Content-Type: application/json
      body:
        customer_id: "cust_12345"
        amount: 4999
        currency: USD
        description: "API Labs test order"
        metadata:
          source: apilabs.ai
          environment: "{{environment}}"
    tests:
      - id: create_valid_order
        description: Should create order successfully.
        expect:
          status: 201
          model: CreateOrderResponse
      - id: reject_missing_customer_id
        description: Should fail when customer_id is missing.
        mutate:
          remove: request.body.customer_id
        expect:
          status: 400
          model: ErrorResponse

DSL Sections

The apilabs.ai DSL is organized into a small set of core sections.

Section	Purpose
api	Defines API metadata such as name, version, and base URL
environments	Defines environment-specific execution contexts
auth	Defines authentication and secret resolution
models	Defines reusable request and response schemas
routes	Defines executable API endpoints
models_ref	References reusable models inside routes
request	Defines headers, parameters, and request payloads
response	Defines expected API responses
tests	Defines executable validations and edge-case tests

High-Level Structure

api:
environments:
auth:
models:
routes:

A route typically contains:

routes:
  - id:
    name:
    method:
    path:
    models_ref:
    request:
    tests:

The DSL is intentionally optimized for:

◆ AI readability
◆ Minimal duplication
◆ Secure execution
◆ Git versioning
◆ Automated testing
◆ Agentic workflows

Guidance

Authentication

Secrets should never be stored directly inside the DSL. Use secure secret references through the apilabs.ai Auth Manager:

auth:
  type: bearer
  apilabs_auth_mgr_ARN: aws-sm://orders/prod/access-token

The Auth Manager can securely resolve credentials from:

◆ AWS Secrets Manager
◆ HashiCorp Vault
◆ Azure Key Vault
◆ GCP Secret Manager
◆ Future enterprise secret providers

Models

Define reusable request and response schemas under models. Routes should reference models using models_ref.

models_ref:
  request: CreateOrderRequest
  response:
    201: CreateOrderResponse

Benefits:

◆ Better AI schema understanding
◆ Reusable contracts
◆ Easier validation
◆ Cleaner Git diffs
◆ OpenAPI compatibility
◆ Improved AI-generated test creation

Tests

Each route can contain executable tests. Supported testing concepts include:

◆ Assertions
◆ Payload mutation
◆ Edge-case validation
◆ Schema verification
◆ AI-generated test expansion

tests:
  - id: reject_missing_customer_id
    mutate:
      remove: request.body.customer_id
    expect:
      status: 400

Environment Support

Use environments to separate execution contexts:

◆ localhost
◆ development
◆ staging
◆ production
◆ VPN/private infrastructure

environments:
  dev:
    base_url: http://localhost:3000
  prod:
    base_url: https://api.example.com

Combined with the apilabs.ai Secure Tunnel, AI agents can safely execute APIs against:

◆ localhost
◆ private VPC APIs
◆ Kubernetes clusters
◆ VPN-only infrastructure
◆ internal enterprise systems

Summary

The apilabs.ai API Contract DSL is more than API documentation. It is:

◆ An executable API contract
◆ An AI execution layer
◆ A testing specification
◆ A workflow orchestration definition
◆ A secure APIOps foundation for AI-native development

Built for the future of APIs, AI agents, and autonomous software systems.

Status

This spec is a working draft. Fields and semantics may change before GA. Feedback welcome via the contact form.