Organisations with dozens of systems usually face a tangle of point-to-point connections: each system talks directly to several others, each with its own protocol and contract. The result is that changing one system breaks several more, and adding a new channel, such as a mobile app, takes months of integration work. When a team wants to know what a customer's latest transaction was, it has to ask three systems and combine the answers by hand. The integration layer, in effect, is spread invisibly across every system and owned by nobody.
This matters because the speed of an organisation's digital transformation is directly tied to the speed of its integration. If every new product requires reconnecting to the central systems, the cost of testing new ideas becomes prohibitive. Each direct connection is also an unsupervised security point: who is calling, with what authorisation, at what rate? Without a shared layer, those questions are answered separately for every connection, which in practice means nobody holds the complete answer.
The preferred architecture places two complementary patterns side by side. The API gateway is the single entry point for synchronous interactions: a consumer sends a request and receives an answer in the same moment. The gateway applies authentication, authorisation, rate limiting, versioning and observability uniformly. Event-driven architecture serves asynchronous interactions: when something happens, such as an account opening or an address change, the source system publishes an event and any interested system consumes it, without the source needing to know who the consumers are. A durable message queue between them guarantees that no event is lost.
The first practical consideration is contract design. APIs and events are both contracts and should be treated as such: with an explicit schema, explicit versioning and a clear rule for compatible versus breaking changes. For example, adding an optional field to a customer-updated event is a compatible change, but changing the type of an existing field requires a new version published alongside the old one for a transition period. A central schema registry lets teams check compatibility automatically before deployment rather than discovering a break in production.
The second consideration is choosing correctly between synchronous and asynchronous. The rule of thumb: if the consumer needs the answer immediately to continue its own work, use an API; if it only needs to know that something happened, use an event. A balance enquiry is synchronous. Notifying the anti-money-laundering system about a transaction is asynchronous. Many performance and coupling problems in organisations come from asynchronous interactions implemented as synchronous calls, where one slow system slows the entire chain.
The third consideration is end-to-end observability. When a request enters through the gateway, passes through several services and produces several events, the team must be able to follow the whole path with a single correlation identifier. That identifier must travel in the API headers and in the event metadata alike. Without it, debugging a problem becomes manual matching of timestamps across the logs of several systems, which at peak hours is practically impossible.
The common pitfalls fall into a few groups. First, turning the API gateway into a home for business logic; the gateway should enforce policy, not make business decisions. Second, fat events that carry the whole record and bind consumers to the source's internal structure, or thin events that carry only an identifier and force everyone to call back. Third, ignoring ordering and duplication; a consumer must be able to recognise a repeated event and handle one that arrives out of order. Fourth, having no owner for the integration layer, which quietly returns it to the previous state.
At Niadad, this triad is implemented as three complementary platforms. Sepehr («سپهر») is the enterprise API gateway: authentication, authorisation, rate limiting, versioning and observability for all synchronous interactions. Jarian («جریان») is the event platform: publishing, subscription and event schemas with retained history. Payam («پیام») is the durable message queue that provides guaranteed delivery and error handling for asynchronous work. In Niadad's banking programme these three form the integration backbone and connect to the identity, party and data layers.
An API gateway and an event-driven architecture are two answers to two different questions, and a mature organisation has both. What turns them into one infrastructure is explicit contracts, shared identity and end-to-end observability. With those three in place, adding a new channel or system changes from a multi-month project into a matter of days. That is the real measure of an integration layer: not how elegant its diagram looks, but how little it stands in the way of the next change.