# The API is only one part of a complex integration The difficult work usually begins where the documentation ends. Data models disagree, old and new systems need to coexist, another company controls approval, and someone must own what happens after the first successful request. ## The connector already works. Depending on it is another matter A complex integration is not one request leaving one system and arriving at another. It is a change in how data, responsibility, and failure move through the business. ### The same concept does not mean the same thing in both systems Both sides have fields for the same data, but the rules, history, and exceptions do not line up one to one. ### Old and new need to coexist The operation cannot pause for a clean cut. Accounts, records, or workflows must move in stages without creating two conflicting truths. ### Part of the timeline belongs to another company Certification, security review, a merge queue, or production access can sit outside your control without sitting outside your responsibility. ### People will build on top of it An undocumented endpoint is just an endpoint. Whoever builds on it needs examples, well-defined failures, and a way to know what happened. ## An adapter can pass its tests and still fail the operation Most integration estimates cover the happy path between endpoints. Production risk lives around that path: historical data, partial failure, retries, external review, cutover, monitoring, and the person responding when reality differs from the schema. - Translation rules disappear into code without a business decision behind them. - A partial migration leaves two systems claiming to be the source of truth. - Go-live is promised against a calendar controlled by several teams. ## Where “just integrate the API” goes wrong The visible coding task is scoped. Everything required to trust it is left implicit. ### Scope endpoint to endpoint The estimate covers authentication and payloads, but not data ownership, migration, reconciliation, or the workflow on either side. ### Promise the external calendar Engineering can be review-ready on time while approval still belongs to another team. Treating those as the same commitment creates false certainty. ### Leave operations for later Documentation, observability, retries, support, and rollback become urgent only after someone already depends on the integration. ## Design the whole change, not just the connector We treat the integration as a product: implementation, migration, external coordination, and operations are planned together, and someone answers for it after go-live. 1. **Map the whole path.** Identify who creates the data, who changes it, where exceptions live, and which system is authoritative at each stage. 2. **Prove translation and failure.** Test real examples, edge cases, retries, and partial states before volume and dependencies make them expensive. 3. **Stage the cutover.** Move a controlled slice first, keep the current operation available, and make reconciliation explicit before expanding. 4. **Operate and explain it.** Ship monitoring, actionable logs, documentation, examples, and a clear owner for incidents and external review. ## One data layer instead of repeated infrastructure As Silo expanded, every new network could have created another indexer, API, monitoring path, and set of integration instructions. Bleu built a documented data layer across them and took responsibility for its production operation. **[Silo Finance](https://bleu.builders/cases/silo-finance/)** — One team owned the data layer end to end: indexing, APIs, monitoring, and infrastructure cost control. > “Easy to work with. Take ownership, which is not easy. Can be trusted to deliver, also not easy.” > > — Siros, Silo Finance ## Start with the integration that looks “almost straightforward” The useful conversation starts outside the endpoint list: data, external dependencies, migration, operational risk, and who needs to trust the result. - The systems and teams on both sides of the integration - Real records, including the exceptions a clean sample hides - The external approvals and operational deadline shaping the work ## Useful when the integration carries operational risk Some connectors really are straightforward, and then you do not need us. The model makes sense when the surrounding decisions matter as much as the endpoints. ### A good fit - Several systems or teams disagree about data or responsibility - Migration, coexistence, certification, or external review is part of the work - The integration needs production ownership, documentation, and monitoring ### Probably not a fit - A commodity connector with stable schemas and complete documentation - No historical data, cutover, external approval, or operational consequence - A named internal owner only needs a short implementation sample ## Neighboring problems - [Some software work gets harder the moment you try to delegate it](https://bleu.builders/problems/hard-to-delegate/) - [More engineers will not fix a product area that still has no owner](https://bleu.builders/problems/ownership-not-headcount/) - [The AI pilot worked. The operation still cannot depend on it](https://bleu.builders/problems/ai-stuck-before-production/) ## Tell us which integration it is and where it stalls today.