1 agents

API Gateway Specialist Agent

API Gateway Specialist Agent

Overview

The API Gateway Specialist Agent operates as an L3 strategic command agent within the Primary domain of the Prismatic Platform. This agent designs and maintains gateway and facade patterns that manage API traffic routing, request transformation, and cross-cutting concerns such as authentication, rate limiting, and request logging. The gateway layer serves as the single entry point for all external API consumers, providing a unified interface to the platform's distributed service architecture.

In the Prismatic ecosystem, the API gateway is not a simple reverse proxy. It implements intelligent request dispatch through the platform's auto-introspecting architecture, where Prismatic API scans all facade modules at boot time and routes incoming requests to the appropriate module functions. The API Gateway Specialist ensures this dispatch mechanism handles edge cases including partial module availability, graceful degradation during deployments, and proper error propagation from backend services to API consumers.

The gateway also serves as the platform's primary security boundary for API traffic. Authentication verification, authorization checks, rate limit enforcement, and request validation all execute at the gateway level before requests reach backend modules. This centralized security enforcement ensures consistent policy application across all API endpoints without requiring each backend module to implement its own security checks.

Architecture

The API Gateway Specialist manages a layered gateway architecture that processes requests through a pipeline of middleware stages before dispatch to backend modules.

Request Pipeline. Incoming requests pass through a configurable middleware pipeline implemented as Plug chains in the Phoenix router. The pipeline stages execute in order: CORS policy application, authentication verification, rate limit checking, request validation, request transformation, dispatch to backend module, response transformation, and response logging. Each stage can short-circuit the pipeline, returning an error response without invoking subsequent stages.

Facade Module Registry. The gateway maintains an ETS-backed registry of available facade modules discovered through the auto-introspection scanner. Each registry entry maps a {app, action} tuple to the corresponding module and function. The registry is refreshed at boot time and can be hot-reloaded when new modules are deployed.

Circuit Breaker Layer. Each backend module endpoint is wrapped in a circuit breaker that monitors response times and error rates. When a backend module's error rate exceeds the threshold, the circuit breaker opens, routing requests to a fallback handler that returns a cached response or a graceful degradation message. This prevents a failing backend from consuming gateway resources and degrading the experience for consumers of healthy endpoints.

defmodule PrismaticAPI.Gateway do
  use Phoenix.Router

  pipeline :api do
    plug :accepts, ["json"]
    plug PrismaticAPI.Plugs.CORS
    plug PrismaticAPI.Plugs.APIAuth
    plug PrismaticAPI.Plugs.RateLimiter
    plug PrismaticAPI.Plugs.RequestValidator
  end

  scope "/api/v1", PrismaticAPI do
    pipe_through :api
    get "/health", HealthController, :check
    get "/endpoints", EndpointController, :list
    get "/:app/:action", DispatchController, :dispatch_get
    post "/:app/:action", DispatchController, :dispatch_post
  end
end

defmodule PrismaticAPI.DispatchController do
  use PrismaticAPI, :controller

  def dispatch_get(conn, %{"app" => app, "action" => action} = params) do
    case resolve_endpoint(app, action) do
      {:ok, module, function} ->
        case check_circuit_breaker(module, function) do
          :closed -> safe_apply(module, function, extract_args(params))
          :open -> fallback_response(conn, app, action)
        end
      {:error, :not_found} ->
        send_resp(conn, 404, encode_error("Endpoint not found"))
    end
  end
end

Core Capabilities

  • Request routing and dispatch with pattern-based routing rules that map incoming API requests to appropriate backend modules, supporting both static configuration and auto-discovered endpoints
  • Facade pattern implementation that presents simplified, consumer-friendly interfaces over complex internal service architectures, hiding implementation details and inter-service dependencies
  • Cross-cutting concern management including authentication verification, rate limiting enforcement, request/response logging, and CORS policy application at the gateway level
  • Circuit breaker and fallback routing that detects backend service failures and automatically routes requests to fallback handlers or cached responses, maintaining API availability
  • Request transformation pipelines that normalize incoming requests, validate payload schemas, and transform responses to match consumer-expected formats across API versions
  • Gateway health monitoring with real-time metrics on request throughput, error rates, latency percentiles, and circuit breaker states for operational visibility

Implementation

The gateway implementation builds on Phoenix's router and plug pipeline architecture with additional ETS-backed service discovery and circuit breaker integration.

The dispatch controller resolves API requests to backend module functions through the facade module registry. Resolution is O(1) through ETS lookup, ensuring that gateway routing does not add significant latency to request processing. The safe_apply/3 function wraps the backend module invocation with error handling, preventing backend exceptions from crashing the gateway process.

Rate limiting uses a sliding window algorithm backed by ETS counters, supporting per-endpoint and per-consumer rate limits. The rate limiter emits telemetry events when limits are approached (80% utilization warning) and when limits are exceeded (429 response), enabling proactive capacity management.

Integration Points

AgentRelationshipPurpose
api-design-specialist-agentDesign AuthorityReceives API design specifications for gateway implementation
cloud-security-specialistSecurity PartnerCoordinates gateway security policies and authentication flows
alert-management-specialistHealth MonitorRoutes gateway health alerts including circuit breaker events
aiad-dashboard-commanderVisibilityDisplays gateway metrics on monitoring dashboards
absolute-enforcement-commander-v6Quality GateValidates gateway configuration against quality standards

Operational Workflow

The gateway operational workflow covers both request processing and gateway configuration management.

Request Processing Flow. Each incoming request traverses the middleware pipeline. CORS headers are applied first, followed by authentication verification (API key or token validation). Authenticated requests are rate-limited based on consumer identity and endpoint. Valid requests are dispatched to the backend module through the facade registry. Responses are transformed if version translation is required, and the complete request/response cycle is logged with timing metrics.

Circuit Breaker Management. Circuit breakers monitor backend module health through a sliding window of recent responses. When the error rate exceeds the threshold (default 50% over 10 requests), the circuit breaker opens, diverting traffic to the fallback handler. After the cooldown period (default 30 seconds), the circuit breaker enters half-open state, allowing a single probe request. If the probe succeeds, the circuit closes and normal routing resumes.

Gateway Configuration Updates. Configuration changes (new rate limits, updated authentication rules, modified CORS policies) are applied through the AIAD Hot Reload Coordinator, enabling live gateway updates without restart. The facade module registry is refreshed when new backend modules are deployed, enabling immediate availability of new API endpoints.

NABLA Compliance

The API Gateway Specialist operates under NABLA Infinity axiom compliance for gateway operations.

Signal Plurality. Backend module health is assessed through multiple independent signals: response codes, response latency, error rates, and circuit breaker state. No single signal triggers a routing change; the circuit breaker algorithm considers the composite signal.

Provenance Mandatory. Every request routing decision is logged with provenance: the matched route, the resolved backend module, the authentication result, the rate limit status, and the response code. This audit trail enables debugging of routing issues and security analysis of access patterns.

Time Decay. Rate limit windows implement explicit time decay. Request counts older than the window period do not affect current rate calculations. Circuit breaker state includes temporal context -- the time of last failure, time of last probe -- to prevent stale failure data from keeping circuits open indefinitely.

Configuration

config :prismatic_api, PrismaticAPI.Gateway,
  rate_limit_window_ms: 60_000,
  rate_limit_default: 100,
  circuit_breaker_threshold: 0.50,
  circuit_breaker_window: 10,
  circuit_breaker_cooldown_ms: 30_000,
  cors_allowed_origins: ["*"],
  request_logging: true,
  telemetry_prefix: [:prismatic_api, :gateway]

The AIAD specification at .aiad/agents/api-gateway-specialist-agent.agent.md defines L3 strategic command authority with enforcement block requiring no-mercy-no-doubts doctrine compliance.

Performance

MetricCurrentTargetDescription
Request routing latency< 5ms< 10msTime for gateway dispatch (excluding backend processing)
Authentication check< 2ms< 5msTime for API key or token validation
Rate limit check< 1ms< 2msTime for sliding window rate limit evaluation
Gateway throughput> 5k req/s> 2k req/sMaximum sustained request rate
Circuit breaker response< 1ms< 5msTime to return fallback response when circuit is open
Endpoint discovery< 1ms< 5msO(1) ETS lookup for facade module resolution

Connect & Contribute

Created by Tomáš Korcak (korczis) | Open Source under GHL

Related Content

Color Teams

6 adversarial-defensive security teams with 20 specialized agents.

Doctrine

NO MERCY, NO DOUBTS - the universal doctrine governing all operations.

OSINT Sources

121+ intelligence sources across Czech, EU, and global registries.
Back to Agent Ecosystem