Skip to content
Banking & Finance

BIAN in Practice, Part 3: From Semantic APIs to Implementation Contracts

Turn a BIAN reference operation into a testable bank contract with clear ownership, identifiers, completion evidence, retry behaviour and controlled extensions.

Perspectives · BIAN in Practice · Part 3

In Part 2, a fictional lending workshop separated offer handling from the core system’s responsibility for establishing a loan record. Part 3 takes the next step: what must the origination team, core team and consumers agree before that interaction becomes an API contract?

A reference operation can give teams common language. A deployable contract must also explain which request is permitted, what changes, how the result is established and how the client recovers when it cannot see the response.

Start from the reference, then state the local decision

BIAN’s public release 14.0.0 Customer Offer artefact includes operations to update and retrieve information about the product-initialisation request. That gives the team a reference for the offer-side activity. It does not establish that a local update creates a core loan record or disburses funds. [1][2]

Document the release, artefact and selected operation, then explain what the bank adopts, adapts or excludes. In this fictional bank, the origination service records progress for the offer, while the core or its authorised business service applies loan establishment. The table below is a proposed local design, not a prescribed BIAN mapping.

BoundaryIllustrative local contractEvidence and owner
Offer activityUpdate or retrieve offer-side establishment request information.Origination service owns the offer status and linked references.
Establishment commandSubmit a request only when the approved offer version, accepted terms and required conditions match.Authorised lending service validates authority; core establishes the operational record.
Outcome queryRetrieve state using the original establishment reference.The authoritative record confirms whether the loan was established.
Completion notificationInform consumers of the established loan record under an agreed event contract.The event is derived from confirmed establishment; consumers handle duplicates.

Distinguish schema compatibility from business compatibility

An OpenAPI description gives consumers a structured view of operations, payloads and responses. A schema may accept a valid amount and date even when the selected offer has expired or the requester lacks authority. Define preconditions, valid transitions, the authoritative write and side effects alongside the schema. [3]

A contract can break without a field being removed. Changing when a status becomes final, reinterpreting an amount, or treating an optional field as mandatory in practice can break existing consumers. Review these semantic changes with the teams that rely on the contract.

Use identifiers that survive the handoff

In the example, an offer ID identifies the proposal, an establishment request ID identifies an instruction, and the loan ID identifies the established record. A trace ID helps operations follow a call. Record their relationships without giving a channel authority to invent a loan ID or infer that the record exists.

Bind the request to the approved offer version and relevant accepted terms. Define who can initiate it and whether conditions can change between submission and application. If the same key is reused with changed material terms, handle it as a conflict rather than silently treating it as the original request.

Give each state a meaning the consumer can use

State in the fictional contractWhat it meansWhat the consumer does
AcceptedThe establishment instruction was durably accepted for processing.Track the original reference; do not announce a loan or funds.
EstablishedThe authoritative operational loan record is confirmed.Use the confirmed loan reference; continue any separate disbursement flow.
RejectedThe request could not proceed under the specified rules.Use the safe reason and the documented next action.
Outcome uncertainThe caller cannot yet establish the result from available evidence.Use the agreed status or reconciliation path; do not create a new instruction.

An HTTP 202 can communicate acceptance without completion. Transport status, the bank’s business state and customer-facing language need explicit mapping. An established loan record does not mean funds have been credited. [4]

Work through the difficult response first

The core commits the loan record, but the connection closes before the origination service sees the response. The workflow still shows pending and its replicated ODS read has not caught up.

The contract should let the owner trace the original establishment reference to an authoritative outcome. If a retry is allowed, its scope and time window must be agreed and enforced by the service controlling the effect. The ODS may support reads after replication; it cannot establish a loan, execute a retry or change the source record.

Exercise two additional cases: concurrent repeats of the same request, and a repeat with altered terms. The first must not establish another record under the agreed repeat contract. The second must be detected as a conflict. Test authorisation on the outcome query as well as on the command.

Govern the differences you intentionally introduce

Record each extension, its owner, its business reason and its impact on consumers. Separate reference release upgrades from local API versions. Preserve the artefact and mapping used for a released contract so a future team can explain what changed. Do not infer certification or interoperability from a matching name or a schema that happens to validate.

At review, ask for a reference-to-contract mapping, a state model, an authority matrix and test evidence for failure and recovery. Compare these with the actual gateway, middleware and core responsibilities. A single architecture owner can coordinate the decision, while the bank retains approval of credit authority, service acceptance and residual risk.

Our perspective

A semantic API gives the bank a shared way to describe an interaction. The implementation contract makes that interaction dependable. Consumers should be able to tell what they may ask for, what happened, and how to recover the result when the response is uncertain.

Next in the series: Part 4 will examine authoritative information, replicated read models and events across Service Domains.

Continue with Learning

The offer is accepted. Has the loan been established? Turn the lending reference into a testable local contract.

Sources & further reading

  1. BIAN official artefact repository
  2. BIAN Customer Offer semantic API — release 14.0.0
  3. OpenAPI Specification
  4. RFC 9110 — HTTP Semantics
Learn the topic

Put this perspective into practice.

Explore the concepts, make a decision and test what changes when the situation changes.

Topics: , , , ,

Leave a Reply

Your email address will not be published. Required fields are marked *

An invitation to contribute

Everyone has a perspective worth hearing.

A lesson from your profession. An experience that changed your mind. A question you think deserves a better conversation.

Share your perspective