API Products

Packaging bank capabilities for internal and external consumers

A capability with a contract

An application programming interface (API) product is a defined capability offered to a known type of consumer with a usable contract, access model, operating promise and accountable owner. Publishing endpoints alone does not explain who may call them, what the result means or how failures are resolved.

Separate internal applications, regulated third-party access, commercial partners and corporate integrations. They can use similar technical components while having different authority, data scope and support commitments. Do not expose staff-only fields because an internal endpoint is convenient to reuse.

Contract the business meaning

Specify field definitions, currency, balance types, timestamps, optionality, null behaviour, pagination and errors. Distinguish an empty result from information unavailable or outside scope. Describe cursor behaviour and ordering so a consumer can retrieve a changing transaction history without silently losing records.

For a write, define instruction identity, idempotency, duplicate handling and business states. An HTTP 200 can acknowledge processing without establishing final settlement. A timeout needs guidance about enquiry and safe retry. Rate limits, validation failures and unavailable dependencies should be distinguishable without leaking prohibited details.

Enforcement behind the interface

Authenticate the caller, establish its role and check the customer or corporate authority required for the action. Enforce resource and field scope on the server. A valid token does not permit every account, and hiding a field in the portal does not prevent retrieval through the API.

The security profile should match the actual ecosystem. FAPI 2.0 Security Profile is a final OpenID Foundation specification for high-security OAuth-based access. It covers confidential clients and sender-constrained tokens. It is not a universal law, and older FAPI 1.0 baseline/advanced terminology should not be presented as the structure of FAPI 2.0. Conformance requires the selected profile's actual requirements and assumptions, not a mix of convenient features.

Technical access authority and legal permission need linked but distinct records. Include actual actor attribution so investigations do not mistake a partner payment for a staff action. Protect logs and avoid recording credentials or unnecessary sensitive payloads.

Versioning and operating promises

A change to field meaning can break consumers even if the JSON schema remains valid. Publish version and deprecation policy, test compatibility and notify affected consumers under the applicable requirements. Migration windows and regulatory notifications depend on the arrangement; do not invent a universal deadline.

Availability measures should describe the consumer's usable journey, not merely gateway reachability. Support needs correlated references, actionable errors and incident contacts. Set capacity and retry budgets against realistic traffic, including reconnection and batch refresh after an outage.

Worked example: zero and unavailable are mixed

In this fictional product, a partner budgeting app interprets a null available balance as zero. During an upstream issue it tells customers they have no spendable money. The schema allowed null, but the documentation did not explain it and the sandbox never produced the condition.

The bank clarifies the semantics, supplies a suitable unavailable state and representative fixtures, and coordinates the partner correction. It reviews affected journeys rather than describing the incident as only a partner rendering problem. No party should substitute a made-up balance to maintain a successful response.

Tests and economics

Test denied roles, wrong accounts, revoked access, conflicting idempotency keys, pagination changes, timeouts, semantic compatibility and recovery. Sandbox results do not establish production readiness unless identity, configuration and dependencies are also checked.

Track successful business outcomes, errors by cause, support demand, compatibility failures and the cost of serving the capability. Endpoint count and call volume alone say little about value. For mandated access, commercial pricing choices must respect the applicable access duties; a paid product should not be used to obscure what must be provided.

Takeaway

An API product is a contract for a banking capability with enforced authority and an operating owner. Correct meaning and safe failure are part of the product.

Continue to Consent Management.