What the Estate Already Knows: Assembling an Integration Bill of Materials Without a Questionnaire

Ask a platform team for the component inventory of a container image and the answer will arrive in minutes, formatted to a recognised specification and complete with versions and licences. Ask the same organisation for a list of every interface its business runs on — the nightly extract to a fulfilment partner, the webhook from a payment provider, the message queue behind the customer portal, the SFTP drop that feeds the finance system — and the answer is usually a diagram dated three years ago and a name of somebody who has since left.

The asymmetry is worth sitting with. Software composition analysis became routine because a regulator, a customer or a procurement framework demanded it. Integration inventory has no equivalent forcing function, and so it remains the least-documented part of most estates, despite being the part through which money, personal data and operational risk actually move.

A bill of materials, not a diagram

The term is borrowed deliberately. A software bill of materials (SBOM) works because it is machine-readable, versioned, attributable and rebuilt automatically whenever the underlying artefact changes. An integration bill of materials should inherit those properties rather than the properties of an architecture poster.

In practical terms, it is a maintained record with one entry per interface, each carrying a consistent set of fields. It is not a network diagram, though it should be reconcilable with one. It is not a six-month-old enterprise architecture repository entry. It is not a spreadsheet held by a single engineer, however capable, because a spreadsheet held by one person has an availability risk equal to that person's notice period.

The fields that earn their place

Resist the temptation to design a forty-column schema on the first pass. A workable minimum looks something like this:

• Identifier and version — a stable name for the interface, with a version that changes when the contract changes.
• Endpoints and protocol — REST, SOAP, SFTP, message queue, file drop, database link; the hosts and paths as they exist in production.
• Data classification — what actually crosses the boundary, mapped to your UK GDPR classification scheme, with special category data called out explicitly.
• Contract reference — the data processing agreement, the statement of work, the schedule that says who may call whom and how often.
• Owner — a named team and a role, not an individual's mailbox.
• Dependencies — upstream systems, downstream consumers, and any shared component whose failure would take the interface with it.
• Credentials and certificates — where keys live, who rotates them, and when the TLS certificate next expires.
• Volume and limits — rate limits, throughput expectations, batch windows, service credits.
• Monitoring route — the alert that fires when the interface fails, and the team that receives it.
• Exit route — how the interface would be withdrawn, by whom, and at roughly what cost.

That last field is the one most often omitted and most often missed. An interface with no documented exit is a commitment of indefinite duration, and it should be recorded as such rather than left implicit.

Start from evidence, not from interviews

Workshops are the traditional starting point and the least reliable one. People describe the estate as they believe it to be, which is rarely as it is configured. The estate itself, however, leaves a long trail of artefacts, and those artefacts are the sensible foundation for a first draft.

Useful sources, roughly in order of yield:

• Gateway and middleware exports. API gateways, integration platforms and enterprise service buses hold route tables, consumer registrations and policy definitions. An export gives you the interface list for free.
• Identity and access records. OAuth client registrations, service principals and app registrations in the identity provider expose machine-to-machine relationships that no one has drawn on a diagram.
• Certificates and DNS. Certificate transparency logs, internal certificate inventories and public DNS records reveal external endpoints, including ones commissioned outside the change process.
• Monitoring and observability. Service maps from APM tooling, log-based dependency graphs and egress firewall records show what actually talks to what, as opposed to what was designed to.
• Scheduling and file transfer. Batch schedulers, job definitions and managed file transfer servers hold a great many interfaces that never appear in an API catalogue.
• Commercial records. Supplier contracts, purchase ledger entries, and per-message or per-connection licence fees map closely onto live integrations. Finance often holds a better interface inventory than IT, expressed in invoices.

The first pass will be over-inclusive. That is the correct outcome. Record each entry with a status — active, deprecated, unknown — and resolve the unknowns over time rather than blocking publication on completeness.

Treat it as a versioned artefact

An integration bill of materials that lives only in a wiki will decay within a quarter. The organisations that sustain one tend to store it in the same repository discipline as code: plain-text or YAML entries, held in version control, reviewed through the change process, and published as a read-only view for auditors and architects.

There is no need to force integration inventory into CycloneDX or SPDX, although both now carry service components that can accommodate it if a single format is preferred. What matters is the underlying habit: every change to an interface produces a diff, every diff is reviewed, and every entry carries a date and an author.

Where it repays the effort

Three situations justify the work more than any business case document.

Incident response. When a component is compromised, the first question is which interfaces touched it. An inventory turns that from a two-day forensic exercise into a query.

Supplier change. Outsourcing rules and contract renewals increasingly ask for fourth-party visibility — who your suppliers depend on, and how you would disentangle yourself. An exit route recorded at design time is far cheaper than one reconstructed under commercial pressure.

Audit. Whether the driver is the Cyber Assessment Framework, a sector regulator, or a customer's due diligence questionnaire, the questions converge on the same ground: what data moves, where, under whose control, and how do you know.

The first ninety days

A pragmatic sequence for UK organisations starting now: spend the first fortnight on automated exports from gateways, identity and monitoring. Spend the next month reconciling those against contracts and spend data. Use the following month to assign owners and mark the unknowns honestly. Publish version 0.1 at the end of the quarter, with a stated review cadence and a link from the change process.

Prioritise criticality over coverage. A complete record of the twenty interfaces that carry regulated data is worth more than a partial record of two hundred that carry none. The document itself is not the deliverable; the habit of keeping it current is.