Spec Extensions Reference

Complete reference for all x-barbacane-* OpenAPI extensions.

Summary

x-barbacane-upstream

Defines a named upstream backend connection.

Location

Server object in servers array.

Schema

x-barbacane-upstream:
  name: string          # Required. Unique upstream identifier
  timeout: duration     # Optional. Request timeout (default: 30s)
  retries: integer      # Optional. Retry attempts (default: 0)

Properties

Duration Format

Durations support:

• 5s - seconds
• 100ms - milliseconds
• 1m - minutes
• 1h - hours

Example

servers:
  - url: https://api.example.com
    description: Production API
    x-barbacane-upstream:
      name: main-api
      timeout: 30s
      retries: 2

  - url: https://payments.example.com
    description: Payment Service
    x-barbacane-upstream:
      name: payments
      timeout: 60s
      retries: 3

x-barbacane-dispatch

Specifies how to handle a request for an operation.

Location

Operation object (get, post, put, delete, patch, options, head).

Schema

x-barbacane-dispatch:
  name: string    # Required. Dispatcher name
  config: object  # Optional. Dispatcher-specific configuration

Properties

Dispatcher: mock

Returns static responses.

x-barbacane-dispatch:
  name: mock
  config:
    status: integer   # HTTP status (default: 200)
    body: string      # Response body (default: "")

Dispatcher: http-upstream

Reverse proxy to HTTP/HTTPS backend.

x-barbacane-dispatch:
  name: http-upstream
  config:
    url: string       # Required. Base URL (HTTPS required in production)
    path: string      # Optional. Upstream path template (default: operation path)
    timeout: number   # Optional. Timeout in seconds (default: 30.0)

Examples

Mock response:

paths:
  /health:
    get:
      x-barbacane-dispatch:
        name: mock
        config:
          status: 200
          body: '{"status":"ok"}'

HTTP upstream proxy:

paths:
  /users/{id}:
    get:
      x-barbacane-dispatch:
        name: http-upstream
        config:
          url: "https://user-service.internal"
          path: "/api/v2/users/{id}"

Wildcard proxy:

paths:
  /proxy/{path}:
    get:
      parameters:
        - name: path
          in: path
          required: true
          schema:
            type: string
      x-barbacane-dispatch:
        name: http-upstream
        config:
          url: "https://backend.internal"
          path: "/{path}"
          timeout: 10.0

Secret References

Config values can reference secrets instead of hardcoding sensitive data. Secrets are resolved at gateway startup.

Example with secret reference:

x-barbacane-dispatch:
  name: http-upstream
  config:
    url: "https://api.example.com"
    headers:
      Authorization: "Bearer env://UPSTREAM_API_KEY"

If a secret cannot be resolved, the gateway fails to start with exit code 13.

See Secrets Guide for full documentation.

x-barbacane-middlewares

Defines a middleware chain.

Location

• Root level: Applies to all operations (global)
• Operation level: Applies to specific operation (after global)

Schema

x-barbacane-middlewares:
  - name: string    # Required. Middleware name
    config: object  # Optional. Middleware-specific configuration

Properties

Middleware Override

When an operation defines a middleware with the same name as a global one, the operation config overrides the global config for that middleware.

Examples

Global middlewares:

openapi: "3.1.0"
info:
  title: My API
  version: "1.0.0"

x-barbacane-middlewares:
  - name: request-id
    config:
      header: X-Request-ID
  - name: rate-limit
    config:
      requests_per_minute: 100
  - name: cors
    config:
      allowed_origins: ["https://app.example.com"]

paths:
  /users:
    get:
      # Inherits all global middlewares
      x-barbacane-dispatch:
        name: http-upstream
        config:
          url: "https://api.example.com"

Operation-specific middlewares:

paths:
  /admin:
    get:
      x-barbacane-middlewares:
        - name: auth-jwt
          config:
            required: true
            scopes: ["admin:read"]
      x-barbacane-dispatch:
        name: http-upstream
        config:
          url: "https://api.example.com"

Override global config:

# Global: 100 req/min
x-barbacane-middlewares:
  - name: rate-limit
    config:
      requests_per_minute: 100

paths:
  /high-traffic:
    get:
      # Override: 1000 req/min for this endpoint
      x-barbacane-middlewares:
        - name: rate-limit
          config:
            requests_per_minute: 1000
      x-barbacane-dispatch:
        name: http-upstream
        config:
          url: "https://api.example.com"

Common Middleware Configurations

auth-jwt

- name: auth-jwt
  config:
    required: true
    header: Authorization
    scheme: Bearer
    issuer: https://auth.example.com
    audience: my-api
    scopes: ["read"]

rate-limit

- name: rate-limit
  config:
    quota: 100             # Maximum requests allowed in window
    window: 60             # Window duration in seconds
    policy_name: "default" # Optional: name for RateLimit-Policy header
    partition_key: "client_ip" # Options: "client_ip", "header:<name>", "context:<key>"

Returns IETF draft-ietf-httpapi-ratelimit-headers compliant headers:

• RateLimit-Policy: Policy description (e.g., default;q=100;w=60)
• RateLimit: Current limit status
• Retry-After: Seconds until quota reset (only on 429)

cors

- name: cors
  config:
    allowed_origins: ["https://app.example.com"]
    allowed_methods: ["GET", "POST", "PUT", "DELETE"]
    allowed_headers: ["Authorization", "Content-Type"]
    max_age: 86400

cache

- name: cache
  config:
    ttl: 300                  # TTL in seconds (default: 300)
    vary: ["Accept-Language"] # Headers that differentiate cache entries
    methods: ["GET", "HEAD"]  # Cacheable methods (default: GET, HEAD)
    cacheable_status: [200, 301, 404] # Cacheable status codes

Adds X-Cache header to responses:

• HIT: Response served from cache
• MISS: Response not in cache (will be cached if cacheable)

request-id

- name: request-id
  config:
    header: X-Request-ID
    generate_if_missing: true

idempotency

- name: idempotency
  config:
    header: Idempotency-Key
    ttl: 86400

x-barbacane-observability

Configures observability settings for tracing, logging, and SLO monitoring.

Location

• Root level: Applies to all operations (global defaults)
• Operation level: Overrides global settings for specific operation

Schema

x-barbacane-observability:
  trace_sampling: number         # Optional. Sampling rate 0.0-1.0 (default: 1.0)
  detailed_validation_logs: bool # Optional. Log validation details (default: false)
  latency_slo_ms: integer        # Optional. Latency SLO threshold in milliseconds

Properties

Examples

Global observability settings:

openapi: "3.1.0"
info:
  title: My API
  version: "1.0.0"

x-barbacane-observability:
  trace_sampling: 0.1          # Sample 10% of traces
  latency_slo_ms: 500          # Alert if requests exceed 500ms

paths:
  /users:
    get:
      x-barbacane-dispatch:
        name: http-upstream
        config:
          url: "https://api.example.com"

Operation-specific override:

x-barbacane-observability:
  trace_sampling: 0.1   # Global: 10% sampling

paths:
  /critical-endpoint:
    get:
      x-barbacane-observability:
        trace_sampling: 1.0     # Override: 100% for critical endpoint
        latency_slo_ms: 100     # Stricter SLO
      x-barbacane-dispatch:
        name: http-upstream
        config:
          url: "https://api.example.com"

Debugging with detailed validation logs:

paths:
  /validate:
    post:
      x-barbacane-observability:
        detailed_validation_logs: true  # Log full validation error details
      x-barbacane-dispatch:
        name: http-upstream
        config:
          url: "https://api.example.com"

SLO Monitoring

When latency_slo_ms is configured, the gateway emits a barbacane_slo_violation_total metric each time a request exceeds the threshold:

barbacane_slo_violation_total{method="GET",path="/users",api="users-api",slo_ms="500"} 12

This integrates with Prometheus alerting:

# Prometheus alert rule
groups:
  - name: barbacane
    rules:
      - alert: HighLatencySLOViolations
        expr: rate(barbacane_slo_violation_total[5m]) > 0.01
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High SLO violation rate"

Validation Errors

Complete Example

openapi: "3.1.0"
info:
  title: Complete Example API
  version: "1.0.0"

servers:
  - url: https://api.example.com
    x-barbacane-upstream:
      name: main-backend
      timeout: 30s
      retries: 2

x-barbacane-middlewares:
  - name: request-id
    config:
      header: X-Request-ID
  - name: cors
    config:
      allowed_origins: ["*"]
  - name: rate-limit
    config:
      quota: 100
      window: 60
      partition_key: "client_ip"

paths:
  /health:
    get:
      operationId: healthCheck
      x-barbacane-dispatch:
        name: mock
        config:
          status: 200
          body: '{"status":"healthy"}'
      responses:
        "200":
          description: OK

  /users:
    get:
      operationId: listUsers
      x-barbacane-middlewares:
        - name: cache
          config:
            ttl: 60
      x-barbacane-dispatch:
        name: http-upstream
        config:
          url: "https://api.example.com"
          path: /api/users
      responses:
        "200":
          description: User list

  /users/{id}:
    get:
      operationId: getUser
      x-barbacane-dispatch:
        name: http-upstream
        config:
          url: "https://api.example.com"
          path: /api/users/{id}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: User details

  /admin/users:
    get:
      operationId: adminListUsers
      x-barbacane-middlewares:
        - name: auth-jwt
          config:
            required: true
            scopes: ["admin:read"]
        - name: rate-limit
          config:
            quota: 50
            window: 60
      x-barbacane-dispatch:
        name: http-upstream
        config:
          url: "https://api.example.com"
          path: /api/admin/users
      responses:
        "200":
          description: Admin user list