Principles of API integration design for scalable, secure IT solutions with data, process, and security in mind.
23.9.2025 Designing API integrations helps connect different information systems into a single architecture, from CRM and 1C to marketplaces and payment services.
This is not only about code, but also about business processes, data, and security. Reading time: 8 min.
Companies rarely use just one information system.
There are accounting, warehouse, production, an online store, CRM, marketplaces, e-commerce services, and payment gateways.
To work as a single organism, these components must exchange data quickly, reliably, and according to the rules. API integrations become the connecting link: they enable information flow and automate chains of actions.
However, simply having software interfaces does not solve every problem.
It is necessary to build an integration architecture that matches business goals, accounts for process specifics, and ensures data quality.
Otherwise, the company risks ending up with many chaotic connections, dependencies, and errors.
In essence, API integration design is part of business process management: as in BPM, it is necessary to clearly describe where and how interaction happens, model possible scenarios, analyze them, monitor them, and update them in time as the business evolves.
Before writing code and configuring exchanges, you need to understand which processes are affected. The BPM concept emphasizes that processes are an organizational asset and must be made transparent, formalized, and continuously improved. The same applies to integrations: they must fit into business processes rather than try to replace them.
: It is necessary to describe current operations: how order processing works, how documents are generated, and where reference data is stored. This is done using diagrams (BPMN, SIPOC) and interviews with stakeholders. Bottlenecks are identified: manual entry, duplication, delays, and errors. Based on this information, you determine which data should move between systems and for what purpose. For example, if a customer portal needs to check warehouse stock, inventory information must be transferred.
To calculate bonuses, CRM must receive payment history data. These data flows become candidates for API integrations.
Each entity - product, customer, contract - should have a single source of truth. 1C stores legally significant information. CRM may contain working contacts. The warehouse system owns the actual stock. When designing the integration, define where a record is created, where it is updated, and who has the right to edit it. If you do not, the data breaks apart and turns into a communication breakdown between systems.
When designing an exchange, you need to answer this question: how exactly will the systems communicate? There are two main approaches.
This is a direct request-response model: one system calls another and waits for an immediate result. This interaction is useful when an operation must finish before the user can continue, such as checking stock during checkout or calculating shipping cost. Advantages: simplicity and predictable wait time. Disadvantages: tight coupling - if the service is unavailable, the entire process stops, and cascading failures are possible.
: Data is transferred as messages (events) through a queue or bus. The sender releases the message and does not wait, while the receiver picks it up when ready. This approach works well for processing high volumes of operations: order creation, status updates, and catalog synchronization. Events do not block users, and the system can process them at its own pace.
Drawbacks: additional infrastructure is required (message brokers), duplicate messages appear, and sequence tracking becomes necessary.
Most often, a hybrid approach is used. Some information is requested on the fly, while some is sent as events. For example, cart confirmation happens synchronously, while sending notifications to logistics and updating reports happens asynchronously. This hybrid balances convenience and reliability.
Chaos begins where every interface speaks its own language.
To avoid misunderstandings, a canonical model is created - a shared vocabulary. This vocabulary describes entities (product, order, customer) and attributes (name, code, quantity, price).
Each system involved in the exchange converts its data to the canonical model and back.
This reduces the number of point-to-point connections and simplifies future development.
After creating the common model, define the contracts:
Which operations are available (get stock, create an order, update status). Which fields are required.
Which error codes can be returned.
Standards can be used for documentation, but it is important that the document is understandable to everyone: technical specialists, business analysts, and lawyers.
A contract is a legal document between systems; it defines who is responsible for what.
In the real world, requests can be duplicated. A user may click a button twice, the network may resend a packet, or a message broker may deliver a duplicate. To avoid creating duplicate orders or charging money twice, operations must be idempotent: a repeated request produces the same result. For this, a unique idempotency key is passed so the system can check whether the request has already been processed. If it has, it returns the result; if not, it creates the record and stores the key.
When using asynchronous queues, assume that some messages may be lost or delivered more than once. A common practice is at-least-once delivery, which guarantees that an event arrives at least once. The system must be able to filter duplicates. A dead-letter queue is also important for messages that cannot be processed, for example because of an invalid format. These messages are sent for manual review, otherwise they can cause harm.
API is flexible. Business moves forward, and the set of fields changes.
To make changes without breaking anything, you need to:
Introduce new versions: v1, v2, and so on.
Breaking changes (removing a field, changing its value) belong in a new version.
Changes that do not break the contract, such as adding an optional field, can be made in the existing version.
Inform partners and internal teams about planned changes, the timeline for retiring old versions, and migration.
Customer data, payments, and personal information are confidential. The integration must protect them: identification and permissions.
Each system must prove its identity, for example using a token or certificate.
Access is granted only to actions that are allowed.
There is no need to give one system access to all operations if it uses only one. Encryption. For channels, use secure protocols (TLS/HTTPS). For storage, use disk encryption.
Secrets (passwords, keys) should be stored in dedicated services, not in configuration files. Logging.
Logs should record who called the method, with what data, and what the result was.
Logs are stored in accordance with personal data legislation requirements. Validation of incoming data.
Validation of formats, ranges, and checksums.
You cannot trust an external request; always verify that the data is correct and valid.
Integration is not a one-time project. It lives in a constantly changing environment.
To respond quickly to failures, observability tools are needed: Metrics.
Response time, request volume, error rate, queue length, CPU load.
This data makes it possible to spot problems before the customer notices them. Tracing.
The system must pass a unique request ID through all services.
This helps identify where the process is slowing down and determine which part of the chain failed. Alerts.
Thresholds and rules are configured: when response time is exceeded, a queue fails, or toxic messages accumulate, specialists are notified.
It is also important to have a test environment (sandbox) where changes can be checked safely without affecting the live system.
To keep integrations alive rather than letting them degrade, you need a governance element: an interface registry.
A list of all APIs, their purpose, owner, version, and documentation.
This helps identify which services use the interface and who is responsible for the change.
A team that approves new integrations, ensures there is no duplication, and helps choose the right tool and pattern. Component library.
A collection of ready-made solutions: templates for integration with 1C, address validation, and currency conversion.
This speeds up development and reduces the number of errors. Change calendar.
A clear implementation plan, with timelines, stakeholders, testing phases, and retirement of old versions.
Let’s look at a simplified order placement scenario that shows how an integration can work:
The customer places an order through the mobile app.
The app makes a synchronous request to the order system to get the order number and delivery time.
The order system creates a record and immediately sends an asynchronous message to the warehouse: "Item needs to be picked."
At the same time, it sends an event to the payment service.
The payment service reserves the funds and, if successful, publishes the event "Payment successful."
If an error occurs, for example a bank refusal, an event "Payment failed" is sent.
The warehouse receives the event and starts picking. After packing, it publishes "Order ready for shipment".
The notification service subscribes to all events.
It sends chat messages to the customer: "Order created," "Payment confirmed," "Shipped."
The analytics system receives the same events, records the time at each stage, and calculates metrics such as fulfillment time and the share of successful payments.
Each message has an idempotency key; if it is repeated, the service recognizes it and does not create a duplicate.
This omnichannel approach makes it possible to separate processes and avoid one subsystem depending on another.
If the payment service is unavailable, the order is saved and the customer receives a notification to retry the payment.
If the warehouse is overloaded, the task can be delayed, but the data will not be lost.
Do not try to automate chaos.
Start by describing and optimizing the processes. Only then integrate.
Separate internal and external models.
Inside a system, data can be stored in whatever format is convenient; for exchange, use a canonical model. Avoid unnecessary coupling.
Do not connect every system to everything.
Use message buses, facades, and anti-corruption layers. Do not cut corners on security.
Even if an integration is internal, attackers can exploit it.
Try to use CIS equivalents.
The terms API, REST, and event will still appear, but it is important to explain what they mean for employees who do not speak English. Plan for future evolution.
Build in versioning, extensibility, and the ability to replace components from the start.
API integration design is not just technical work.
It is the management of relationships between different systems and people, part of modern business process management culture.
It is important to define goals in advance, document processes, create a unified data vocabulary, choose the right exchange method (synchronous, asynchronous, or hybrid), ensure security, monitor data quality, and evolve the system.
A well-designed integration makes a company flexible, transparent, and resilient to market change.
It makes it easy to add new sales channels, services, and partners without rewriting the business logic. With proper support and version management, it also reduces total cost of ownership and increases customer satisfaction.
