Skip to content
Art2link ESB v2.02 LTS HomeDocumentationBlogContact
Core concepts/Adapters/API adapter
Adapter

API adapter

The HTTP transport. Hosts an endpoint when bound to a receive port, dispatches outbound requests when bound to a send port. Both directions support one-way and two-way modes.

ADAPTER · RECEIVE · SEND API HTTP transport — Listener on the receive side, Caller on the send side Shipping DIRECTION ↓ ↑ Receive & Send MODES One-way · Two-way AUTHENTICATION API Authentication PORT Receive or Send RESPONSE Payload

The API adapter is the HTTP transport for Art2link ESB. The platform exposes it as two adapter objects according to the Listener/Caller naming convention: bound to a receive port it is the API Listener (hosts an endpoint and accepts inbound traffic); bound to a send port it is the API Caller (reaches outbound to an endpoint). The two objects are different selections in the UI; this article treats them as one adapter because the underlying protocol and configuration model is one.

Both sides of the same protocol

The split is direction, not function. A Listener has to expose an endpoint and accept inbound connections; a Caller has to reach out and manage retries, timeouts, and response handling. Splitting them in the platform lets each adapter focus on the work its side requires.

SAME PROTOCOL HTTP RECEIVE SIDE API Listener External RECEIVE PORT Exposes an endpoint accepts inbound connections Brings a message into the bus SEND SIDE API Caller SEND PORT Reaches outbound manages retries & response Endpoint Takes a message off the bus
Receive side — the API Listener

Bound to a receive port, the API adapter turns the port into an addressable HTTP endpoint. External callers issue requests against the configured path; the adapter accepts them, runs the receive port's inbound stages, and publishes the resulting message to the bus.

Both modes are supported. One-way returns immediately after publishing; two-way holds the caller's connection open and waits for a matching response message on the bus.

One-way Caller API LISTENER request Bus 202 ACCEPTED Caller releases immediately. No reply correlated back. Webhooks, fire-and-forget ingestion. Two-way Caller API LISTENER request held Bus response message 200 OK + body Caller waits; response correlated. Match driven by Response Subscription Expression. Request/response APIs, synchronous lookups.
Two-way correlation — the Response Subscription Expression

In two-way mode on the receive side, the adapter has to know which bus message is the response to the request it just received. That is the job of the receive port's Response Subscription Expression: a Boolean predicate the bus evaluates against every published message; the first match becomes the response delivered back to the caller.

The expression is evaluated in the same engine used by send/loopback/null port subscriptions, with one important addition: it can reference values that belong to the original inbound request. The most useful of these is a correlation token (a request id, a unique header, a generated GUID) promoted as a variable at the start of the receive port's inbound flow and matched on the outbound side of whichever port produces the response.

EXTERNAL CALLER POST /orders X-Req-Id: abc-123 API LISTENER · RECEIVE PORT two-way, holding connection VARIABLE CAPTURE corr := header(X-Req-Id) on the inbound side Bus request message published with promoted property: corr_id = "abc-123" downstream port processes; eventually publishes a response carrying the same corr_id DOWNSTREAM SEND PORT subscribes, processes, produces response Outbound: variables.copy(corr_id) -> response message Response is republished with promoted: corr_id = "abc-123" the value the listener will match on RESPONSE SUBSCRIPTION EXPRESSION evaluated on every publish {{Promoted.Response.corr_id}} == {{Variable.corr}} match: the response with this caller's correlation token ✓ MATCH → reply
If no message matches inside the request timeout, the caller receives a timeout status (typically 504) and the held connection is released. The bus state itself is unaffected — the in-flight messages are not rolled back. If a late response arrives after the timeout, it remains on the bus and is treated as an unsubscribed message.
Send side — the API Caller

Bound to a send port, the API adapter dispatches an HTTP request to a configured endpoint. The send port carries the request configuration — method, URL, headers, body — and the adapter handles the dispatch and response.

One-way mode fires the request and continues; the HTTP status is checked for success/failure but the response body is discarded. Two-way mode waits for the HTTP response and republishes it to the bus as a payload message, ready for a downstream port to subscribe to.

One-way Bus API CALLER request Endpoint Fire and continue. Status checked; response body discarded. Use when the response carries no value downstream. Two-way Bus API CALLER request Endpoint response republished Response becomes a bus message. Body and status are published as a payload; any port subscribing to it picks it up. Use when the response feeds the next step.
Request shape (send side)

The send port configures the outbound request the API Caller will issue. URL and body support templating against variables, message properties, and xPath into the message body — the same expression engine used elsewhere on the port.

METHOD GET POST PUT PATCH DELETE URL TEMPLATE https://api.partner.example/orders/{{Variable.partner_id}}/lines/{{xpath(/Order/Id)}} HEADERS X-Request-Id: {{Variable.correlation_id}} Content-Type: application/json Authorization: handled by the Authentication BODY { "order": "{{xpath(/Order/Id)}}", "total": "{{xpath(/Order/Total)}}" } leave blank for GET / DELETE
Authentication

The API adapter pairs with an API Authentication. The same Authentication shape is used on both sides — the runtime applies it differently depending on direction:

  • Send side (API Caller): the Authentication presents credentials on the outbound request. The adapter injects them automatically — never set an Authorization header by hand on the Request Headers list; it will be overwritten.
  • Receive side (API Listener): the Authentication validates credentials presented by inbound callers. Where an Authentication is required and the inbound credential is missing or invalid, the listener returns 401 without invoking the rest of the receive port.

Supported credential shapes (verify against product before relying on names): Bearer token, Basic, API key in header, API key in query, OAuth 2.0 client credentials, and (receive-side only) mTLS.

Routing on a shared ingress — publish-time uniqueness

Every API Listener in the solution is hosted under the same base URL. The path alone does not tell the runtime which receive port a request belongs to, so the listener routes on the inbound credential and headers instead: the combination of the Bearer token value and the matching header properties is what selects the destination port.

That combination has to be unique. If two Published receive ports declare the same Bearer-plus-header combination, an inbound request matches both and the runtime cannot decide where to route it. To prevent it, the combination is validated for uniqueness across the whole system — not just within an Application — at the moment a port is Published.

  • Draft — allowed. A Draft is inert and takes no part in routing, so a colliding combination can sit in Draft without conflict.
  • Publish — blocked. Publishing a port whose Bearer-plus-header combination already belongs to another Published port fails validation; the port stays a Draft with nothing lost.
Exact-combination match. The check today compares the full Bearer-plus-header combination for an exact duplicate. It does not yet catch overlapping combinations — e.g. one port matching X: 1 and another matching X: 1 plus Y: 2, where a request carrying both still satisfies both ports. Keep header match sets disjoint until overlap detection is added.
What you configure on the API adapter

Placeholder field sets — verify against the running product. Fields differ by side.

Receive side — API Listener
Path — required; URL path the endpoint is hosted at, relative to the runtime's base URL. May include path parameters (e.g. /orders/{id}) that are promoted into properties on the inbound message.
HTTP Methods — required; one or more of GET, POST, PUT, PATCH, DELETE. Methods not selected return 405.
Accepted Content Types — optional; restricts inbound media types.
Max Body Size — optional; rejects oversized bodies with 413.
Request Timeout — required for two-way; how long the listener will hold the connection waiting for a matching response message before returning a timeout status.
Default Response Status — one-way only; the status code returned after publishing to the bus. Defaults to 202 Accepted.
Response Status From Message — two-way only; an optional expression letting the matching response message specify the HTTP status (e.g. {{Promoted.Response.status_code}}). Defaults to 200.
Authentication — required when the endpoint is not anonymous; picker filtered to API Authentication objects in the same Application.
Send side — API Caller
HTTP Method — required; one of GET, POST, PUT, PATCH, DELETE.
URL Template — required; absolute URL with optional template tokens for variables, message properties, and xPath expressions.
Request Headers — optional; one row per header. Values are templatable. The Authorization header is owned by the Authentication.
Request Body — optional; raw body or templated payload. Ignored for methods that do not carry a body.
Content-Type — optional shortcut; sets the Content-Type header without typing it in the Headers list.
Timeout (seconds) — optional; per-request timeout.
Follow Redirects — optional toggle; default off.
Authentication — required when the endpoint requires credentials; picker filtered to API Authentication objects in the same Application.
i
The Response Subscription Expression is a property of the receive port, not the adapter. It is configured one screen over from the adapter binding because it applies whenever two-way mode is enabled, regardless of which adapter the port is bound to. See the Receive port article for that field's reference.

That is the API adapter

HTTP transport, one adapter, two product objects. API Listener accepts, API Caller dispatches. Two-way correlation on the receive side via Response Subscription Expression; two-way payload return on the send side. Back to Adapters.