Forem: Nico

One gateway, many specs: how Barbacane unifies your API ecosystem

Nico — Tue, 05 May 2026 08:04:12 +0000

Most API tooling assumes one repository, one specification. But your architecture doesn't work that way.

In our previous article, we explored how Barbacane eliminates configuration drift by compiling your OpenAPI spec directly into the gateway's runtime artifact. One spec, one .bca file, zero drift.

But what happens when your architecture has more than one spec?

The Multi-Spec Reality

In a typical microservices setup, your API surface isn't described by a single file. Whether you're working contract-first or generating specs from code, you end up with multiple specifications:

A User Service with its own openapi.yaml
An Order Service with its own openapi.yaml
An Inventory Service exposing both REST endpoints and event consumers, described across OpenAPI and AsyncAPI files
Event schemas scattered across repos

Each file is validated in isolation, deployed independently, and versioned on its own timeline. Single-spec tools can't see across these boundaries, so cross-service mismatches only surface at runtime. The feedback loop is as slow as it gets: write specs, deploy, discover the conflict in production, fix, redeploy.

One Command, Multiple Specs

Barbacane's compile command accepts multiple specification files in a single invocation:

barbacane compile \
  -s services/user-service/openapi.yaml \
  -s services/order-service/openapi.yaml \
  -s services/inventory-service/openapi.yaml \
  -s services/inventory-service/asyncapi.yaml \
  -m barbacane.yaml \
  -o gateway.bca

The compiler parses every file (OpenAPI 3.x and AsyncAPI 3.0.x) and merges their routes into a single .bca artifact. The output message tells you exactly what you got:

compiled 4 spec(s) to gateway.bca (23 routes, 5 plugin(s) bundled)

One artifact. One routing table. One deployment.

What Multi-Spec Compilation Actually Does

When you pass multiple specs, the compiler:

Parses each file independently. OpenAPI and AsyncAPI specs are each validated against their respective standards.
Merges routes into a unified routing table. All operations from all specs end up in a single routes.json inside the .bca artifact. The gateway doesn't care which file a route came from; it serves them all.
Detects routing conflicts. If two specs define the same path and method combination (e.g., both declare GET /users/{id}), compilation fails with error E1010. This is a hard gate: you cannot produce an artifact with ambiguous routing.
Bundles everything together. WASM plugins, dispatcher configurations, and the original source specs are all packaged into the artifact. The source specs remain accessible at /__barbacane/specs for documentation and debugging.

This isn't magic. It's the same compilation pipeline applied across multiple input files. But the practical impact is a meaningful shift left: routing conflicts that would previously surface as mysterious 404s or wrong-handler bugs in production now fail your build.

Specs Stay Accessible at Runtime

Compilation merges routes, but the original source specs aren't thrown away. They're embedded in the .bca artifact and served by the gateway at /__barbacane/specs:

GET /__barbacane/specs

This returns an index of every spec that was compiled into the running artifact, with links to the full OpenAPI and AsyncAPI documents. The served specs are stripped of Barbacane-specific extensions (x-barbacane-*), so what your API consumers and documentation tools see is clean, standard OpenAPI and AsyncAPI with no vendor-specific noise. And because these are the exact specs that were compiled, they can't drift from what the gateway is actually running.

No separate spec hosting. No stale docs. The gateway is the documentation server.

A Practical Example

Consider an e-commerce platform with four services:

User Service      → openapi.yaml
Order Service     → openapi.yaml
Inventory Service → openapi.yaml + asyncapi.yaml
Notification Svc  → asyncapi.yaml

Without multi-spec compilation, you'd deploy each service's gateway configuration independently, trusting that teams coordinated their path prefixes and schema versions. With Barbacane:

barbacane compile \
  -s services/user-service/openapi.yaml \
  -s services/order-service/openapi.yaml \
  -s services/inventory-service/openapi.yaml \
  -s services/inventory-service/asyncapi.yaml \
  -s services/notification-service/asyncapi.yaml \
  -m barbacane.yaml \
  -o gateway.bca

If the Order Service accidentally defines a route that collides with the User Service, compilation fails. You find out in seconds, not after a deploy.

CI/CD Integration

Multi-spec compilation fits naturally into a CI gate. Block merges to main if the combined specs don't compile cleanly:

# .github/workflows/validate-contracts.yml
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Compile gateway artifact
        run: |
          barbacane compile \
            -s services/user-service/openapi.yaml \
            -s services/order-service/openapi.yaml \
            -s services/inventory-service/openapi.yaml \
            -s services/inventory-service/asyncapi.yaml \
            -m barbacane.yaml \
            -o gateway.bca

A non-zero exit code (1 for validation failures, 2 for manifest errors) blocks the pipeline. No ambiguous warnings: either the specs compile together, or they don't.

Progressive Adoption

You don't have to compile everything at once. Start with your most critical services and expand:

# Start with two services
barbacane compile \
  -s user-service/openapi.yaml \
  -s auth-service/openapi.yaml \
  -m barbacane.yaml \
  -o gateway.bca

# Later, add event-driven services
barbacane compile \
  -s user-service/openapi.yaml \
  -s auth-service/openapi.yaml \
  -s order-service/openapi.yaml \
  -s order-service/asyncapi.yaml \
  -m barbacane.yaml \
  -o gateway.bca

Each additional spec increases the surface area of conflict detection. The more specs you compile together, the more mismatches you catch before deployment.

Strengths and Limitations

Multi-spec compilation extends the "compile, don't configure" philosophy across service boundaries, but it's worth understanding what it does and doesn't do today.

What it catches:

Routing conflicts (duplicate path + method across specs)
Spec-level validation errors (malformed OpenAPI/AsyncAPI)
Missing plugin or dispatcher declarations

What it doesn't do (yet):

Cross-spec schema validation (e.g., verifying that an Order object is consistent between two specs)
Breaking change detection between spec versions
Dependency graph analysis between services

These are real limitations. Multi-spec compilation today is primarily about route-level unification and conflict detection, not deep semantic analysis across your API ecosystem. For schema consistency, you'll still need complementary tooling or careful code review.

Shifting Left Across Service Boundaries

The idea behind "shift left" is simple: catch problems earlier in the development lifecycle, when they're cheapest to fix. Linters shift left on code quality. Type systems shift left on correctness. Multi-spec compilation shifts left on cross-service integration.

In our previous article, we showed how Barbacane shifts gateway configuration left by compiling the spec into the runtime artifact. Multi-spec compilation takes this further: instead of discovering that two services disagree on routing after deployment, you discover it at compile time, in CI, on a pull request.

It's not a silver bullet. Cross-service consistency is a hard problem, and route-level conflict detection is just one piece of the puzzle. But it's a piece that most gateway tooling doesn't offer at all, and one that pays off immediately in any multi-service architecture. The earlier you catch a conflict, the less it costs.

Barbacane is open source and available at github.com/barbacane-dev/barbacane. Check the documentation for the full CLI reference and getting started guide.

Beyond configuration drift: how Barbacane reimagines the API gateway with Rust and WASM

Nico — Wed, 29 Apr 2026 18:54:22 +0000

What if your OpenAPI spec wasn't just documentation, but the actual configuration of your production gateway?

For years, API teams have lived with a quiet frustration: the gap between specification and reality. You write a beautiful OpenAPI spec. You configure your gateway (Kong, Tyk, AWS API Gateway) with routes, plugins, and security rules. And then… drift happens. A hotfix bypasses the spec. A plugin gets misconfigured. The documentation lies. The gateway behaves unexpectedly. The contract between frontend and backend fractures.

This isn't a people problem. It's an architecture problem.

Enter Barbacane, a spec-driven API gateway built in Rust that treats your OpenAPI (and AsyncAPI) specification as the single source of truth. No separate configuration files. No UI clicks that diverge from Git. Just your spec, compiled into a self-contained artifact that runs at the edge with memory safety guarantees and sub-millisecond latency.

Let's dive into why this approach matters, and whether it's ready for your production workloads.

The Configuration Drift Crisis

Most API gateways follow the same pattern:

You write an OpenAPI spec (hopefully)
You separately configure the gateway via YAML, UI, or CLI
You hope these two artifacts stay in sync

This dual-source model creates inevitable drift:

# openapi.yaml
paths:
  /users/{id}:
    get:
      security: [{ jwt: [] }]

# kong.yaml (oops, forgot to add auth plugin!)
routes:
  - name: users-get
    paths: [/users/{id}]
    # missing jwt-auth plugin configuration

The result? A route that should require authentication ships to production wide open. Security teams panic. Post-mortems happen. Trust erodes.

Barbacane eliminates this entire class of failure by making drift architecturally impossible.

The Core Insight: Compile, Don't Configure

Barbacane's philosophy is radical in its simplicity:

Your spec is your gateway.

Instead of parsing specs at runtime or maintaining parallel configuration, Barbacane introduces a compilation step:

# Step 1: Write your spec (as usual)
openapi: 3.1.0
info:
  title: User API
  version: 1.0.0
x-barbacane-plugins:
  - name: oidc-auth
    config:
      issuer_url: "https://auth.example.com"
      audience: "my-api"

# Step 2: Compile it
barbacane compile --spec openapi.yaml --manifest barbacane.yaml --output api.bca

# Step 3: Run the gateway
barbacane serve --artifact api.bca

The .bca artifact is a self-contained binary bundle:

Pre-compiled routing trie (FlatBuffers, zero-copy deserialization)
JSON Schema validators for request/response validation
WASM plugins (including your auth middleware)
OPA policies for fine-grained authorization
Dispatcher configurations (HTTP upstreams, Lambda, Kafka)

Critically: no runtime spec parsing. The gateway starts in <100ms because everything is pre-optimized. What you compile is exactly what runs. No surprises.

Architecture Deep Dive: Control Plane vs. Data Plane

Barbacane cleanly separates concerns:

The Control Plane (`barbacane-control`)

Stateful service (PostgreSQL-backed)
Handles spec ingestion, validation, and compilation
Serves artifacts to data planes
Provides UI for fleet visibility

The Data Plane (`barbacane`)

Completely stateless single binary
Loads .bca artifact at startup (memory-mapped via FlatBuffers)
Zero runtime dependencies
Optional WebSocket connection to control plane for health reporting

This separation enables true edge deployment: ship a 15MB static binary with your compiled artifact to a CDN POP, and it runs independently. No coordination required. Scale horizontally by launching more binaries. No consensus protocols. No distributed state.

WASM Plugins: Safety Without Sacrifice

Barbacane ships as a "bare binary" with zero bundled plugins. Every capability (JWT auth, rate limiting, CORS) is implemented as a WASM module explicitly declared in your spec:

x-barbacane-plugins:
  - name: rate-limit
    config:
      quota: 100
      window: 60
      partition_key: "header:x-api-key"

During compilation:

Plugin is fetched from registry (or local cache)
Validated against spec requirements
Bundled into the .bca artifact

At runtime:

Plugins execute in a wasmtime sandbox with strict resource limits
Memory isolation prevents plugin crashes from taking down the gateway
Host functions are capability-gated (e.g., vault access requires explicit grant)
Execution timeouts prevent CPU starvation

This model delivers what Lua plugins in Kong wish they had: true isolation without sacrificing performance. Benchmarks show 261us overhead per WASM middleware invocation, including instantiation, on modern hardware.

Security by Construction

Barbacane's security model is defense-in-depth by design:

Layer	Mechanism	Why It Matters
Memory Safety	Rust + WASM sandbox	Eliminates entire classes of CVEs (buffer overflows, use-after-free)
Secrets Management	Vault fetch at startup only	No secrets in Git, specs, or artifacts. Only in runtime memory
AuthN/AuthZ	Plugin-based + OPA	No vendor lock-in; policies compiled to WASM for speed
Compilation	Fail-fast validation	Blocks dangerous configs early (e.g., `http://` backends in prod)
Transport	Rustls (no OpenSSL)	Memory-safe TLS with modern crypto defaults

For secrets, specs reference them by ID only:

x-barbacane-dispatcher:
  name: http-upstream
  config:
    url: "https://backend.example.com"
    headers:
      Authorization: "Bearer {{ vault://prod/api-gateway/backend-token }}"

At startup, the data plane fetches secrets from a secret manager, never storing them on disk. Rotate keys in your secret manager, and the gateway picks up new values on next restart (or via periodic refresh).

Performance: Why FlatBuffers Matters

Most gateways deserialize JSON configs at startup. For small specs, this is fine. For large specs (500+ routes, complex schemas), it becomes a bottleneck.

Barbacane uses FlatBuffers for its artifact format, a choice that pays dividends:

Zero-copy deserialization: Memory-map the artifact and access data directly
Startup in <100ms: Even for 1,000-route specs
No GC pressure: Critical for latency-sensitive edge workloads
Schema evolution: Backward/forward compatibility built-in

Benchmarks show route lookup in 83 nanoseconds for 1,000 routes, faster than a single L3 cache miss. Full request validation (parameters + body schema) averages 1.2 microseconds. This isn't theoretical; it's the difference between viable and non-viable edge deployment.

Strengths and Tradeoffs

No tool is the right fit for every situation. Here's where Barbacane shines and what to keep in mind.

Strengths

Spec integrity: Drift is architecturally impossible
Security posture: Rust + WASM sandboxing beats Lua/JS runtimes
Edge readiness: Stateless, fast startup, minimal footprint
AsyncAPI support: Rare among gateways. Handles WebSockets/MQTT alongside HTTP
GitOps native: Specs in Git → CI validation → artifact deployment

Tradeoffs to consider

Young project: v0.1.x, actively developed with a growing community
Focused plugin set: ~17 official plugins covering core use cases, with more on the way
Compile-first workflow: Changes go through CI/CD rather than runtime hot-patching
Static backends: Service discovery requires a custom plugin or DNS-based resolution

Barbacane prioritizes configuration integrity and safety over plugin breadth and dynamic reconfiguration. If that tradeoff works for your team, it's worth evaluating.

Competitive Landscape

Gateway	Spec-Driven	Memory Safe	WASM Plugins	Edge-Ready	AsyncAPI
Barbacane	Native	Rust	First-class	Yes	Yes
Kong	Separate config	Lua/Nginx	Experimental	Heavy	No
Tyk	Separate config	Go (GC)	No	Heavy	No
AWS API Gateway	Import only	N/A	No	Managed	No
KrakenD	JSON config	Go (GC)	No	Yes	No

Barbacane targets a different design point than Kong or Tyk: configuration integrity and security over plugin ecosystem breadth.

Who Should Consider Barbacane Today?

Strong fits:

Greenfield APIs with OpenAPI-first development workflows
Edge deployments requiring sub-5ms latency overhead
Security-sensitive domains (fintech, healthcare, govtech)
Teams with mature GitOps/CI-CD practices
Organizations investing in Rust/WASM toolchains

Poor fits:

Legacy systems requiring dynamic runtime reconfiguration
Teams needing 50+ pre-built plugins immediately
Environments without DevOps automation for compilation
Brownfield migrations where spec completeness is low

The Bigger Picture: A Shift in Gateway Philosophy

Barbacane represents more than a new gateway. It's a philosophical shift:

Stop configuring your gateway to match your spec. Make your spec the configuration.

This aligns with broader industry movements:

Infrastructure as Code → Behavior as Specification
Runtime validation → Compile-time validation
Configuration drift → Configuration integrity

It's not the only path forward (declarative gateways like KrakenD point in a similar direction), but Barbacane's Rust/WASM/FlatBuffers stack delivers uniquely strong safety and performance guarantees.

Final Thoughts

Barbacane's spec-driven model addresses a real pain point for API teams: keeping specs and gateway behavior in sync. By compiling the spec into the runtime artifact, that problem goes away entirely. The Rust and WASM foundation delivers strong performance and safety guarantees on top.

The project is at v0.1.x, so it's best suited for new projects where you control the spec lifecycle. If your team already works OpenAPI-first with CI/CD automation, Barbacane fits naturally into that workflow.

The goal: your API contract is your production configuration. Security policies validated before deployment. Edge gateways starting in milliseconds with zero configuration drift. That's the direction we're heading.

Barbacane is open source and available at github.com/barbacane-dev/barbacane. As of February 2026, it remains an early-stage project—evaluate thoroughly before production use.