> For the complete documentation index, see [llms.txt](https://host2host.onibonje.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://host2host.onibonje.com/docs/39-api-gateway-architecture.md).

# API Gateway Architecture

## 1. Overview

Perimeter **HTTP** (REST/JSON, SOAP/XML) and coordination with **WebSocket** real-time ingress via Kong or Apigee. Business logic remains in Camel runtime — gateway handles security, routing, rate limits.

**Full entry point catalog:** [47 Gateway Entry Points](/docs/47-gateway-entrypoints.md) — SFTP, HTTP, WebSocket, MQ, signed URL.

***

## 2. Architecture

```mermaid
flowchart TB
  Partner[Partner systems]
  GW[API Gateway - HTTP SOAP]
  WSG[WebSocket Gateway]
  RT[h2h-runtime Camel]
  SEC[h2h-security plugins]

  Partner -->|REST SOAP mTLS| GW
  Partner -->|WSS real-time| WSG
  GW --> SEC
  SEC --> RT
  WSG --> SEC
  WSG --> RT
```

***

## 3. HTTP Entry Point (REST)

| Product     | Path prefix       | Auth                    |
| ----------- | ----------------- | ----------------------- |
| Payments    | `/v1/payments`    | OAuth2 / API key / mTLS |
| Collections | `/v1/collections` | OAuth2                  |
| Status      | `/v1/status`      | API key                 |
| Statements  | `/v1/statements`  | OAuth2                  |

Paths, methods, and auth are stored per partner in `channel_config` (`channel_type: HTTP`) — gateway routes sync from admin publish.

Route to runtime: `platform-http:` Camel routes resolved by `ChannelConfigResolver`.

***

## 4. SOAP Support

| Use case              | Approach                                                  |
| --------------------- | --------------------------------------------------------- |
| Legacy corporate SOAP | Gateway SOAP → REST bridge OR Camel `cxf` endpoint        |
| Finacle FCUBS         | Internal only (finacle-wrapper) — not exposed to partners |
| Partner SOAP          | WSDL published per product; XSD validation at gateway     |

**Module:** Camel `camel-cxf` in dedicated route or gateway plugin.

Config: `channel_config.protocol: SOAP`, WSDL ref in `connection_params`.

***

## 5. WebSocket Entry Point

Real-time **server-push** for partners — complements sync HTTP; does not replace bulk SFTP.

| Capability      | Configuration                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------ |
| Connection path | `channel_config.connection_params.wsPath`                                                        |
| Handshake auth  | JWT or mTLS — `authMode`, `authRef`                                                              |
| Event push      | `websocket_subscription` → `event_code` from [event catalog](/docs/46-database-driven-events.md) |
| Payload format  | JSON default; optional `transform_spec`                                                          |

**Use cases:** payment status updates, ACK ready notifications, exception alerts, sandbox test progress.

**Implementation:** `h2h-websocket-ingress` module; sessions registered per `partner_id`; push via `EventWebSocketDispatcher` on matching events.

See [47 Gateway Entry Points](/docs/47-gateway-entrypoints.md) §5.

***

## 6. Security Plugins

| Plugin               | Function                                                     |
| -------------------- | ------------------------------------------------------------ |
| `hmac-auth`          | [Security library](/docs/16-security-library.md) HMAC verify |
| `mtls-auth`          | Client certificate validation                                |
| `rate-limiting`      | Per partner tier                                             |
| `correlation-id`     | Inject/generate `X-Correlation-Id`                           |
| `ip-restriction`     | Allowlist from DB                                            |
| `request-size-limit` | Max payload                                                  |
| `ws-jwt-auth`        | WebSocket handshake token validation                         |

***

## 7. Rate Limiting Tiers

| Tier       | HTTP req/min | WS connections | Burst  |
| ---------- | ------------ | -------------- | ------ |
| Standard   | 600          | 2              | 100    |
| Premium    | 3000         | 10             | 500    |
| Enterprise | Custom       | Custom         | Custom |

Stored in `partner.tier` + `channel_config` → gateway sync on publish.

***

## 8. API Lifecycle

1. Define channel in admin (HTTP and/or WebSocket)
2. Assign `integration_profile` and credentials
3. Publish → gateway routes + WS path provisioned
4. OpenAPI / WS connection guide visible on [partner portal](/docs/37-partner-portal.md)

***

## 9. Related Documents

* [47 Gateway Entry Points](/docs/47-gateway-entrypoints.md)
* [16 Security Library](/docs/16-security-library.md)
* [37 Partner Portal](/docs/37-partner-portal.md)
* [31 Error Code Catalog](/docs/31-error-code-catalog.md) HTTP mapping
* [46 Database-Driven Events](/docs/46-database-driven-events.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://host2host.onibonje.com/docs/39-api-gateway-architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.