Digital products ·
An API integration begins with a contract between systems
An API integration lets two systems exchange data and actions according to defined rules. Its quality depends less on making a connection than on describing the contract between both sides precisely.
An API defines a boundary
People work through interfaces: they press a button, complete a form and see a status. Software works through an API, a set of available requests, data formats and responses. One system can request a customer record, submit an order, retrieve a document or trigger an action elsewhere.
An API does not reveal the service’s entire internal mechanism. It defines a limited boundary: which operations are allowed, which fields are required and how success or failure is reported. Products can evolve independently while that contract remains intact.
The journey matters more than the method list
API documentation often begins with endpoints and parameters, but integration design begins with an operational event. What follows a new enquiry? Which system creates the record? Who receives responsibility? What does the customer see if the CRM is temporarily unavailable?
Map the chain from a person’s action to a confirmed result. This reveals the source of truth, waiting points and places where data can split. Each API request then serves a role in the process rather than existing as an ownerless technical capability.
Authentication limits authority
An API key, a user token and a dedicated service account provide different controls. Give an integration the minimum permissions it needs: read specific entities, create one record type or trigger one action. Full administrative access is convenient at first and costly when something goes wrong.
Secrets should not reach browser code, logs or open project files. Define expiry, key rotation and the response to compromise in advance. If an integration cannot be disabled quickly without stopping the whole system, its boundary is poorly designed.
Failure is part of the contract
A connection must work beyond the moments when both sides respond on time. Networks fail, services impose limits, field formats change and the same event arrives twice. The integration needs to distinguish a temporary failure, invalid data and refused access, then choose the correct response.
A retry is safe only when it cannot create a second order or payment. Unique identifiers, idempotent operations and state logs make this possible. A queue can absorb temporary unavailability, but it also needs retry limits and a route for human review.
Shared data needs shared meaning
Fields with the same label can mean different things. Customer status in a CRM may describe sales work, while status in a client portal describes service availability. Before exchange, map entities, dates, currencies, required fields and deletion rules.
Not every value should be copied. Sometimes it is better to retain a reference and request the current value when needed. In other cases, a local copy supports speed and resilience. The decision follows acceptable delay, ownership of updates and the cost of disagreement.
Verify an observable outcome
Monitoring needs to answer more than “is the server online?” It should show how many events arrived, how many completed, where a queue formed and which records need attention. An HTTP `200` response does not prove that the right manager received the enquiry.
Test normal, edge and failure journeys: a missing field, duplicate event, expired token, unavailable service and recovery after an interruption. These scenarios form an acceptance contract and make later changes safer.
When custom development is justified
A ready-made connector may be enough when its model matches the process and errors are easy to repair. Custom integration becomes useful when rules differ, several sources are involved, data is sensitive or a journey must survive partial failure.
Within the Method, I begin with the event, data and responsibility map, then build the smallest complete journey. This prototype reveals real complexity before full digital product development and measures integration by completed work rather than the number of connected APIs.
From an idea to a digital product
If the task calls for a service or internal tool, we can define the first complete journey and a path to a working release.