HTTP API Gateway

Bondy includes an embedded HTTP API Gateway that acts as a reverse proxy, routing incoming HTTP/REST requests to WAMP procedures or to external HTTP/REST APIs.

Overview

HTTP API Gateway

The HTTP API Gateway is a Bondy subsystem that accepts incoming HTTP requests and translates them into WAMP operations (RPC calls or Pub/Sub events) or forwards them to upstream HTTP/REST APIs. It enables WAMP-based microservices to be exposed as standard REST APIs without any additional infrastructure.

The API Gateway allows you to define a complete HTTP/REST API declaratively using a JSON specification document — no coding required. The specification describes how each HTTP endpoint maps to a WAMP procedure call or an external HTTP request, including data transformation using an embedded expression language.

Gateway and Connector, Opposite Directions

Bondy provides two subsystems that work in opposite directions — an ingress gateway and an egress connector:

                   HTTP API Gateway
External  ───HTTP Request──>  Bondy  ───WAMP Call──>  WAMP Service
Client    <──HTTP Response──         <──WAMP Result──

                    HTTP Connector
WAMP      ───WAMP Call──>     Bondy  ───HTTP Request──>  External
Client    <──WAMP Result──           <──HTTP Response──   REST API

	HTTP API Gateway	HTTP Connector
Direction	HTTP → WAMP (or HTTP → HTTP)	WAMP → HTTP
Use case	Expose WAMP services as REST APIs	Consume REST APIs from WAMP clients
Configuration	JSON specification document	`bondy.conf` service definitions
Data transformation	Expression language (Mops)	KWArgs routing (path/query/body)
Authentication	OAuth2, OIDC, WAMP auth methods	Pluggable upstream auth (OAuth2, API keys)

Key Features

Declarative configuration — Define your entire REST API in a JSON document. No custom handler code needed.
WAMP integration — Map HTTP verbs and paths to WAMP procedure calls. The API Gateway handles serialization, error mapping, and response formatting.
HTTP forwarding — Forward requests to external HTTP/REST APIs, acting as a traditional reverse proxy.
Expression language — Transform request and response data using Mops, an embedded logic-less expression language for dynamic value interpolation.
Versioned APIs — Support multiple API versions under different base paths within a single specification.
Security schemes — Built-in support for OAuth2 and OIDC security schemes.
Cluster-wide replication — API specifications are automatically replicated and activated across all nodes in the cluster.

How It Works

An API Gateway Specification is a JSON document that describes:

An API — Identified by a unique ID and bound to a single Realm.
Versions — Each version has a base_path and a set of path definitions.
Paths — Each path maps HTTP methods to operations.
Operations — Each operation defines an action (WAMP call, WAMP publish, HTTP forward, or static response) and a response transformation.

The parser accepts only the keys that each object declares. It refuses a specification with a misspelt or unsupported key, rather than ignoring the key and applying a default. See Validation.

A Declarative Finite State Machine

An API Gateway Specification is effectively a declarative Finite State Machine (FSM) definition. It exposes an HTTP/REST API and converts HTTP nouns and verbs into WAMP or HTTP actions. The FSM state — the API Context — is incrementally and recursively constructed as the specification is evaluated.

Object Tree

API Object
 └── Version Object(s)
      └── Path Object(s)
           └── HTTP Method (GET, POST, PUT, ...)
                └── Operation Object
                     ├── Action Object (wamp_call | wamp_publish | forward | static)
                     └── Response Object

Request Flow

HTTP Client                     Bondy API Gateway                    WAMP Service
    │                                 │                                   │
    │  GET /v1.0/invoices/42          │                                   │
    │────────────────────────────────>│                                   │
    │                                 │  Match path + method              │
    │                                 │  Evaluate expressions             │
    │                                 │  Build API Context                │
    │                                 │                                   │
    │                                 │  WAMP Call: com.billing.get(42)   │
    │                                 │──────────────────────────────────>│
    │                                 │  WAMP Result: {id: 42, ...}      │
    │                                 │<──────────────────────────────────│
    │                                 │                                   │
    │                                 │  Apply response transformation    │
    │  200 {"id": 42, ...}            │                                   │
    │<────────────────────────────────│                                   │

Action Types

The API Gateway supports four types of actions: wamp_call, wamp_publish, static and forward. This section shows wamp_call, static and forward; the Specification Reference describes all four.

WAMP Action

Translates the HTTP request into a WAMP procedure call. The procedure URI, arguments, and kwargs are defined using expressions that can reference the HTTP request data.

json

{
    "type": "wamp_call",
    "procedure": "com.billing.get_invoice",
    "options": {},
    "args": ["{{request.path_params.id}}"],
    "kwargs": "{{request.body}}"
}

Static Action

Returns a static response without making any backend call. Useful for health checks, documentation endpoints, or mock APIs.

json

{
    "type": "static",
    "body": {"status": "ok", "version": "1.0.0"}
}

HTTP Forward Action

Forwards the HTTP request to an external upstream API. Bondy acts as a traditional reverse proxy. When the response body is the upstream body, Bondy returns the upstream bytes and content type as it received them. When the upstream sends no response, Bondy sends the request again only if its method is idempotent, because a request that got no response may still have reached the upstream. See Forward Action.

json

{
    "type": "forward",
    "host": "http://billing.internal:8080",
    "path": "\"/api{{request.path}}\"",
    "headers": "{{request.headers}}",
    "body": "{{request.body}}"
}

Expression Language

Most properties in an API Gateway Specification support expressions using an embedded logic-less domain-specific language called Mops. Expressions are enclosed in double curly braces: \{\{expression\}\}.

Expressions operate on the API Context — a map that contains the HTTP request data, variables, defaults, and action results.

Expression	Evaluates To
`{{request.method}}`	`post`
`{{request.body.sku}}`	`"ZPK1972"`
`{{request.body.price \\|> integer}}`	`13`
`{{request.body.customer.first_name}}`	`"John"`
`{{variables.foo}}`	Value of the `foo` variable

Learn More

See the full Expression Language Reference for details on pipes, type conversions, and context manipulation.

Security Schemes

The API Gateway supports pluggable security schemes:

OAuth2

Provides OAuth2 token endpoints (token issuance and revocation) and protects API routes with bearer token authentication.

json

{
    "security": {
        "type": "oauth2",
        "flow": "resource_owner_password_credentials",
        "token_path": "/oauth/token",
        "revoke_token_path": "/oauth/revoke"
    }
}

OIDC

Integrates with external Identity Providers via OpenID Connect. It registers login, callback, logout and verify endpoints, and the login flow ends with a ticket cookie that authenticates WAMP sessions over the HTTP transports. The version's own paths require that cookie, and a request other than GET, HEAD or OPTIONS must also send its CSRF token in x-csrf-token. See the Security Object.

json

{
    "security": {
        "type": "oidc",
        "provider": "azure"
    }
}

See OIDC Authentication for the complete setup guide.

Loading and Managing APIs

API specifications are loaded, inspected, and deleted via the Admin HTTP API:

Action	Method	URL
Load a spec	POST	`/api_specs`
List all specs	GET	`/api_specs`
Get a spec	GET	`/api_specs/:id`
Delete a spec	DELETE	`/api_specs/:id`

Cluster Deployments

APIs are replicated, synchronised, and activated across the cluster automatically, so that each node serves all the defined APIs.

Next Steps

API Gateway Specification Reference — Full reference for the JSON specification format.
Expression Language Reference — Details on the Mops expression language.
Loading an API Gateway Specification — Step-by-step guide to loading specs via the Admin API.
Marketplace Tutorial — A hands-on tutorial with Python microservices and a VueJS web app.

HTTP API Gateway

Overview

Gateway and Connector, Opposite Directions

Key Features

How It Works

Object Tree

Request Flow

Action Types

WAMP Action

Static Action

HTTP Forward Action

Expression Language

Security Schemes

OAuth2

OIDC

Loading and Managing APIs

Next Steps

HTTP API Gateway Specification

HTTP API Gateway HTTP API

Loading an API Gateway Specification

HTTP Connector

Network Listeners

Marketplace HTTP API Gateway

HTTP API Gateway ​

Overview ​

Gateway and Connector, Opposite Directions ​

Key Features ​

How It Works ​

Object Tree ​

Request Flow ​

Action Types ​

WAMP Action ​

Static Action ​

HTTP Forward Action ​

Expression Language ​

Security Schemes ​

OAuth2 ​

OIDC ​

Loading and Managing APIs ​

Next Steps ​

HTTP API Gateway

Overview

Gateway and Connector, Opposite Directions

Key Features

How It Works

Object Tree

Request Flow

Action Types

WAMP Action

Static Action

HTTP Forward Action

Expression Language

Security Schemes

OAuth2

OIDC

Loading and Managing APIs

Next Steps