When integrations are built one at a time as needs arise, the picture forms like this: someone writes a transfer script between the CRM and the ERP, the warehouse system drops a file for accounting every night, a mobile…
When integrations are built one at a time as needs arise, the picture forms like this: someone writes a transfer script between the CRM and the ERP, the warehouse system drops a file for accounting every night, a mobile app gets its own service. Each connection makes sense on the day it is built. A few years later, mapping which system sends which data to which other system, and in what format, becomes a project of its own.
With an API-first approach, the decision about which contract governs the data comes before another connection joins the pile. The contract is designed before the code, reviewed with the teams that will consume it, and kept in a machine-readable file. The code is written against that contract and tested automatically for conformance.
If each of ten systems can talk directly to every other one, there are 45 possible system pairs, and each pair's connection carries its own data format, error behavior and owner. The real problem is that none of these connections is defined anywhere. If the CRM stores a customer address in one field, the ERP in five and the e-commerce system as free text, every script translates between them its own way, and the translation rule lives only in that script's code. A small field change in one system can quietly break a report that nobody remembered was reading that field.
In a code-first approach, the application comes first and the API documentation is generated from the code afterwards. The application's internal data model then shapes the API, and table names, internal status codes and temporary fields can leak out. Even with accurate documentation, the design decisions were made while writing code, without asking the consumers.
API-first makes the same decisions before the code exists. While there are no consumers yet, renaming a field or changing its type affects nobody; after go-live, the same change means separate adaptation work for every consumer. These contracts are written in open standards such as OpenAPI for HTTP APIs and AsyncAPI for event-driven flows. With the contract in those files, documentation, mock endpoints and client code can be generated from the same source.
An API contract should be clear enough for a consuming team to finish the integration without asking the provider questions. That requires a few decisions while the contract is written.
The first is data ownership. If the CRM is the source of record for customers, other systems read customer data through the CRM's API; contracts written before this decision can lock in setups where two systems update the same data. The second is format rules: when field naming, date format (ISO 8601), currency representation and pagination are the same across all APIs, a team picking up a new API does not have to deal with format differences.
The error model belongs in the contract as well. It should state which HTTP status code comes back for which error condition and how the error body is structured; RFC 9457 (Problem Details for HTTP APIs) defines a common format for that body. Authentication and authorization need decisions too: standards such as OAuth 2.0 for authorization and OpenID Connect for authentication, the permission each endpoint requires, and how many requests per minute the API accepts (rate limiting). Realistic request and response examples for the most common scenarios also go into the contract and change with it.
A contract written once and left alone drifts away from the code. The way to prevent that is to make the contract part of the development process. It lives in the same version control repository as the code, and changes to it go through code review. At the draft stage, a mock endpoint is generated from the contract; the consuming team builds against it before the real service exists, and neither team waits for the other.
Schema validation checks that the provider conforms to the contract, and consumer-driven contract testing checks consumers' expectations automatically. In consumer-driven contract testing, each consumer defines the response it expects from the API as a test; when the provider team changes something, these tests run in the continuous integration pipeline and show which consumers would be affected before the change reaches production. Pact is a widely used tool for this.
Adding an optional field to a response is generally backward compatible; removing a field, changing a field's type or adding a new required request field breaks compatibility (a breaking change). That distinction should be written into the contract and the team's rules, because even a field rename made as "a small fix" can break integrations. When a breaking change cannot be avoided, a new version is published, the support period for the old version is announced in advance, and consumers migrate within that period.
Picture a company that keeps customer information in three different shapes across its CRM, ERP and e-commerce systems, with a separate transfer script running between each pair. Under API-first, the team first designs a single "Customer" resource. The contract states which system generates the permanent customer number, which sub-fields make up an address and which of them are required, and which permission is needed to read fields such as a national ID number or tax number.
The ERP and the e-commerce system now reach customer data through this contract. When a customer record changes, the CRM publishes an event, for example CustomerUpdated; the event has its own AsyncAPI contract containing the customer number, the changed fields and the time of the change. The ERP and the e-commerce system listen to the event and update their own copies, and the transfer scripts between system pairs are no longer needed. If the address format changes, the change is made in one contract and announced under the versioning rule.
Every contract needs an owner. The owning team evaluates change requests and plans breaking changes together with the consumers. Keeping the organization's APIs in a single catalog, with their owners and contract files, reduces the risk of rebuilding an API nobody knew existed.
An API gateway routes traffic, validates access tokens and enforces rate limits; it cannot fix a badly designed contract. For endpoints that return personal data, having each response return only the fields the consumer uses lines up with Article 4 of Türkiye's personal data protection law (KVKK), which requires processing to be relevant, limited and proportionate to its purpose, and with the data minimization principle in Article 5 of the GDPR.
There is no need to rewrite every integration at once. A good first candidate is an integration that many systems depend on and that breaks often; the effect of a contract shows most clearly there. Write its contract, move the old connection to the new API, then repeat the same steps for the next integration. Progress can be tracked through the number of remaining point-to-point connections and the number of breaking changes that reach production without notice.