APIs and Integration
Agree on an API contract before parallel development
Parallel teams need more than a list of endpoints. Agree on data meaning, failure behavior, and review ownership before independent implementations create expensive differences at the integration stage.
Two teams can finish their work and still disagree about what an API does. One treats a missing delivery date as unknown. Another treats it as immediate delivery. A contract should resolve these differences before parallel development turns them into incompatible behavior.
Define decisions, not just field names
OpenAPI describes HTTP API capabilities through a standard interface description that humans and tools can understand.[1] Use it to describe paths, parameters, request bodies, responses, and security requirements. Add examples that explain the business meaning of each important field.
Ask the product owner to resolve missing values, units, time zones, and state transitions. Separate a request accepted for processing from a business action completed. A successful transport response must not become an undocumented promise that every downstream activity has finished.
Make the agreement executable
Recommend a shared specification in version control, with a named owner for each operation. Review example requests alongside expected responses. Give the client team a mock implementation, but label which behaviors the mock does not reproduce.
Use schema checks and consumer tests as different tools. A schema can check the shape you specify. A consumer test can check an assumption about behavior. Neither replaces a discussion about authorization, ordering, or what happens when a dependency fails. Reserve time for integration against the real service.
Keep the first contract narrow enough to review carefully. An unresolved edge case should have an explicit temporary rule, a responsible decision maker, and a test that exposes the limitation to both teams.
Approve a practical readiness checklist
Before teams split their work, ask each side to walk through one successful flow and two failure flows. Do not approve the contract merely because the specification parses. Record open questions as decisions with owners, not informal chat messages.
- Name the business owner and technical reviewer for each operation.
- Define required, optional, and nullable fields separately.
- Describe permission failures, validation errors, and asynchronous completion.
- Agree on example fixtures and a process for reviewing incompatible changes.
Hypothetical example: a delivery appointment
Hypothetical example: a warehouse portal submits an appointment request to a scheduling service. The teams agree that an accepted request returns a tracking identifier, not a confirmed loading slot. A separate status operation reports confirmation or rejection.
The portal team can build a pending screen while the service team implements slot allocation. Both test an unavailable slot and a repeated submission. This preparation costs review time and may delay an early coding start. It is worthwhile when several teams would otherwise build against different interpretations. The next action is a short contract workshop focused on unresolved business meanings, not a broad architecture presentation.
