01 / DEVELOPMENT
Describe the exchange in plain language
An integration moves information or actions between systems. Begin by describing the exchange without naming a library or protocol. Identify the source, the destination, the trigger, the information being transferred, and the result that should follow. This description gives technical and nontechnical participants a shared view of the task. It also exposes whether the proposed connection solves a real workflow problem or merely connects tools because a connection is possible.
Specify which system owns each important fact. If both systems can edit the same field, determine how conflicting updates should be handled. If one system is the source of truth, make that responsibility explicit. A technically successful transfer can still produce an unreliable workflow when ownership is ambiguous. People need to know where a correction belongs and which copy should be trusted when the records differ. Resolve that question before automating the exchange.
Check whether an integration interface is actually available and appropriate. A product's public identity does not establish that it offers an API, an event stream, or a supported export. Look for confirmed documentation and access conditions. A workflow may instead need a file exchange or a deliberate manual step. Choose an approach based on the supported interface and the task's requirements, rather than treating a guessed endpoint or an observed internal request as an official integration contract.
02 / DEVELOPMENT
Define the contract between systems
A data contract describes what information is exchanged and how it should be interpreted. Include field names, types, required values, identifiers, units, time zones, and the meaning of missing data. These details prevent apparently valid records from carrying inconsistent assumptions. For example, an empty field might mean unknown, intentionally blank, or not applicable. The receiving system should not need to guess which meaning the source intended.
Define the timing and delivery expectations. Does the destination need the information immediately, on a schedule, or only when a person requests it? How will the system identify a duplicate event or a repeated request? What happens if the source changes a record after it has been transferred? The right answer depends on the workflow. Clear expectations allow the implementation to handle ordinary delays and repeated delivery without treating them as exceptional surprises.
Permissions are part of the contract. Determine who authorizes the connection, which records it may access, and which operations it may perform. Use the access needed for the task and avoid granting unrelated authority for convenience. Keep credentials outside client-facing code and shared examples. If an integration operates without a person present, identify how its access is maintained and how an owner can revoke it. The connection should remain understandable throughout its life.
03 / DEVELOPMENT
Design for interruptions and maintenance
Assume that a dependency can become unavailable, a request can fail, and a record can be incomplete. Define how failures are detected, which actions can be retried, and which need human review. A retry is appropriate only when repeating the operation has an understood effect. A repeated read is different from repeating an action that creates a record or sends a message. The implementation needs enough information to avoid turning recovery into duplication.
Make failures observable without exposing unnecessary data. Record the operation, relevant identifiers, status, and a useful error description. Avoid placing secrets or excessive personal information in logs. Give the owner a way to distinguish a temporary interruption from a configuration problem or a rejected request. A connection that fails silently can leave two systems looking consistent while important work has stopped moving between them.
Plan for change. Document the supported interface version, the expected schema, and the owner of the integration. Include a small set of representative checks that can be run when the source or destination changes. Define an exit path for disabling the connection without losing the authoritative records. Maintenance is not a separate concern added after launch; it is part of what makes the integration reliable enough for ordinary use.
A small design record
Before implementation, write the source and destination, the trigger, the contract, the access scope, the failure behavior, and the acceptance checks. Keep the record concise and update it when a decision changes. This gives the eventual code a clear purpose and gives future maintainers a way to understand the choices without reconstructing them from requests and log files.
For confirmed company and product information, visit Developers. Explore the rest of the reading room for more general guidance.