An insurer is rebuilding its claims journey. A digital agency in Lisbon builds the customer portal, a software house in Kraków builds the mobile app, and the systems integrator that has maintained the policy administration platform for a decade owns the integration layer. Every fortnight each vendor reports green. End-to-end testing starts six weeks before launch, and on the first morning the portal sends claim amounts as floating-point numbers, the integration layer expects minor currency units as integers, and the policy platform returns a claim status nobody had planned for. Each vendor is right according to its own reading of the requirements. None of them has a document that settles the dispute.
None of this is bad faith or incompetence. It happens because the project had no single, binding description of how its parts talk to each other. The interface emerged as a by-product of implementation rather than as its starting point.
This article is for architects and delivery leads on projects where more than one company delivers the software. The thesis is this: with several vendors, an API specification is not technical documentation but a contractual artefact. The client must own it, not any of the vendors, and conformance with it, not a green status at a steering meeting, should decide whether work is accepted. Plenty of experienced engineers will disagree, because they believe the team implementing a service knows its contract best. I will argue that with one team they are right, and with several companies they are not.
Why does the interface matter more than the code when you have several vendors?
Because you can replace, rewrite or take over any vendor’s code if you have to, but the interface is the only place where the companies’ responsibilities meet. When one team builds both the back end and the app, a mismatch between them costs a conversation at a desk and a fix in two files. When two companies build them under separate contracts, schedules and budgets, the same mismatch costs an email thread, an argument about who is right, a change request on one or both sides and a slipped date.
The scale of the problem is not theoretical. Postman’s State of the API 2025 report, based on responses from more than 5,700 developers, architects and executives, found that 93% of API teams face collaboration blockers and 55% struggle with inconsistent documentation. The same report says 82% of organisations have adopted some level of an API-first approach, but only 25% operate as fully API-first. The gap between those two numbers is exactly where companies declare API-first and, in practice, write the specification after the code.
With one vendor, interface mismatches are a quality problem. With several, they become a governance problem: they affect the schedule, the budget and vendor relationships. So decisions about the interface have to be made where governance decisions are made, on the client side, and recorded in a form that can be checked automatically.
There is one more reason. The interface outlives any vendor contract. In three years the mobile app may move to another company and the integration layer to an in-house team. If the only precise description of the interface sits in the code of a departing vendor, the new team starts with reverse engineering. If it sits in the client’s repository as an approved specification, handover comes down to sharing a file and a conformance test suite.
What does API-first actually mean, and how is it different from code-first?
API-first, often called design-first, is about the order of work: first the interface description is written and agreed, then the code that implements it. In code-first, the team writes the implementation and generates the interface description from annotations in the code. Both can end with the same OpenAPI file. They differ in who makes decisions about the shape of the interface, and when.
The most widely quoted working definition comes from Zalando’s public RESTful API guidelines. Rule 100, “MUST follow API first principle”, requires teams to define APIs before coding the implementation, using a standard specification language, and to ask for review feedback from peers and client developers as early as possible. The guidelines also name the anti-pattern explicitly: publishing API specifications and asking for peer review only after the service has been integrated. And they add two caveats worth remembering. API first is not in conflict with agile development principles, and it does not require complete understanding of the domain and requirements.
That second caveat disarms the most common objection. API-first is not a return to waterfall, with three months of specification before anyone touches code. The specification for one resource or one flow can be drafted in a day or two, reviewed and handed to the teams as the basis for their work. Further pieces follow iteratively. The difference is that every interface change goes through the specification before it reaches the code, not the other way round.
The standard for HTTP APIs is the OpenAPI Specification, maintained by the OpenAPI Initiative. Version 3.2.0 was published on 19 September 2025 and adds, among other things, descriptions of streaming and sequential media types and support for the QUERY method. The specification calls the document describing an API an “OpenAPI Description” and defines it as a formal description of the surface of an API and its semantics. For event-driven communication over queues and message brokers the equivalent is AsyncAPI, covered below.
It also helps to separate API-first from simply having a specification. A company that generates an OpenAPI file from its code and publishes it on a developer portal has a specification, but it is not doing API-first. The decisions about the interface were made in code, and the file merely reflects them. That is enough for documentation. It is not enough to manage several vendors, because nobody other than the author of the code had a chance to challenge those decisions before they became facts.
Who should own the contract when an interface connects two vendors?
This is where most multi-vendor projects go wrong, and where my thesis is most contested. The natural instinct is that the team implementing the service writes the specification, because it knows the service’s constraints best. On a single-vendor project that instinct is sensible. On a multi-vendor project it leads to one company unilaterally setting the working conditions of another.
Suppose vendor A builds the back end and vendor B builds the app. If A owns the specification, A decides how errors look, how pagination works, which fields are mandatory and when the interface changes. B can only react. Every change on A’s side, however justified, means extra work for B, which B prices as a change request to the client. The client pays for decisions it did not make and often did not see.
The answer is not for the client to write the specification from scratch. It is to separate three roles. The author of the draft can be the service provider, because it knows the service best. The reviewers are all consumers: the other vendors and internal teams. The approver sits on the client side: a solution architect, a head of architecture or a small design authority. The file lives in a repository the client owns, and vendors contribute through pull requests.
In practice this means the client needs someone who can read and judge specifications, not just receive them. If there is no such person in the organisation, it is worth hiring or engaging one for the duration of the project. What to expect from an externally engaged solution architect in the first month is covered in our article on bringing in a contract solution architect. What matters is that this architect is not also employed by one of the vendors implementing the interface, or you are back where you started.
The usual objection is that the client will slow everything down, because every change will wait for approval. That is a real risk, and you manage it by setting a response time for change requests, for example two working days, and by automating everything a machine can check. But the alternative is not faster work. The alternative is fast work for one vendor and slow, expensive work for the others, who learn about each change after the fact.
What must an OpenAPI contract contain for an agreement to rely on it?
A specification that serves as a contract between companies must be more precise than typical documentation. If two parties can read it differently, the dispute from the opening of this article comes back. Several elements matter most.
Field types and formats with constraints. “amount: number” is not enough. The contract should settle whether an amount is an integer in minor currency units or a decimal sent as a string, what range of values is allowed and whether the field can be null. The same applies to dates (time zone, format), identifiers (format, length) and status enumerations (the full list, and what happens with an unknown value). For a project handling euros, pounds and Swiss francs, the currency code belongs in the contract too.
Unambiguous operation identifiers. OpenAPI requires each operationId to be unique among all operations described in the API, and it is case-sensitive. These identifiers become method names in code generated by the vendors and references in tests, so changing them after launch is a contract change.
An error model. Every operation should describe its error responses, not just the 200. The contract settles the format of the error body, which HTTP status codes are possible and what the consumer should do with each. This is the most common source of disagreement between vendors, because every company brings its own habits.
Examples. Example requests and responses are not decoration. Mock servers use them to generate responses, and reviewers understand more from them than from the schema. An example that contradicts its schema is a specification bug a linter should catch.
Security. Authentication schemes and permission scopes for each operation. If the client has requirements for system-to-system authentication, they must be visible in the contract, not only in a separate security document.
Webhooks. Since version 3.1.0, published in February 2021, OpenAPI can describe webhooks: incoming calls the API consumer may choose to implement. In a multi-vendor project this matters, because callbacks and notifications are often the least documented part of an integration.
Then there is a list of things OpenAPI does not describe, or describes poorly, that belong in the agreement: response times, availability, rate limits, maintenance windows, incident reporting. Put them in a separate service level schedule and reference the contract’s operations by operationId. That way both documents talk about the same thing rather than two different lists of features.
The design decisions you cannot later reverse without cost are covered at length in our API design best practices checklist. The point here is narrower: in a multi-vendor project each of those promises is a promise one company makes to another, and the client is the guarantor that it will be kept.
How do you describe event-driven integrations in AsyncAPI?
Not all communication between vendors runs over HTTP calls. More and more systems exchange events through a message broker: the back end publishes “claim submitted”, and the policy platform and the notification service consume it. When to choose APIs and when events is covered in our article on ESB, APIs or event-driven architecture. If you choose events, you need a contract just as much, arguably more, because the publisher does not know who consumes its messages and gets no error when a consumer cannot understand them.
The standard for such interfaces is AsyncAPI. Version 3.0.0 was released on 5 December 2023 and brought three changes that matter for multi-vendor projects. First, it decoupled channels and messages from operations, so a channel definition can be reused across documents. Second, it replaced the ambiguous publish and subscribe keywords with send and receive, which describe what your application does. Third, it added request-reply, one of the longest-requested features.
The first change has a direct effect on how you organise work. The “claims” channel and the “claim submitted” message schema can be defined once, in the client’s repository, and each vendor’s AsyncAPI document only states whether it sends or receives on that channel. Changing the message schema is then one change in one place, visible to every participant.
An event contract should settle several things whose absence only shows up in production: which key identifies an event (needed to discard duplicates), whether ordering is guaranteed and within what scope, what a consumer does with a message it cannot process, and how long the broker retains messages. Some of this fits in AsyncAPI itself, some belongs in the channel description or a schedule to the agreement. What matters is that it is written down before the first vendor starts publishing.
How does a mock server let teams work in parallel?
This is the API-first benefit easiest to translate into a schedule. Without an approved specification, the mobile team waits until the back end exposes its first working endpoints, or builds on its own assumptions, which later need fixing. With a specification it can start straight away, against a mock server: a service that responds according to the contract before any real implementation exists.
There are several tools. Prism, an open-source project from Stoplight, turns an OpenAPI 2.0, 3.0 or 3.1 file (or a Postman collection) into a mock server, and can also run as a validation proxy that checks whether a real implementation responds in line with the specification. Microcks, a Cloud Native Computing Foundation incubating project, mocks and tests APIs described in OpenAPI, AsyncAPI, gRPC and GraphQL, as well as SOAP services, so it covers event-driven interfaces too.
On a schedule it looks like this. Week one: the client’s architect and the back-end vendor draft the specification for the first flows, and consumers review it. Week two: the specification is approved and a mock server goes live in an environment shared by all vendors. From then on the back end implements the service, the mobile app builds screens against the mock, and the integrator prepares data mapping from the same schemas. Connecting the real parts is no longer the first encounter with the interface. It is swapping a mock for an implementation that has already passed conformance tests.
Mock servers have limits worth remembering. They respond according to the schema and examples, but they do not reproduce business logic: they will not change a claim’s state after approval, and they will not reject a request that is syntactically valid but makes no business sense. So examples in the specification should include edge cases and errors, and consumer teams should not treat green tests against a mock as proof that the integration works. It is proof that their code understands the contract. Proof that the whole flow works comes only from tests against the real implementation.
How do you write the API contract into a vendor agreement?
A specification with no link to the agreement is good practice that a vendor may or may not follow. To become a governance tool it needs legal standing. That does not require elaborate clauses, just a few provisions.
A technical schedule with a version. The agreement or the statement of work for a stage refers to a specific version of the specification, ideally with a version identifier from the repository, such as a tag or commit hash. Both sides then know which file applies, instead of arguing about which version on the documentation portal was current on the day of signing.
Conformance as an acceptance criterion. Accepting an interface includes automated verification that the implementation responds in line with the contract. The criterion is measurable and does not depend on anyone’s opinion.
A change procedure. Changing the contract requires a request, review by consumers and approval by the client. A backward-incompatible change also requires an impact assessment for the other vendors and a decision about who bears its cost.
Rights in the specification. A specification is a work in its own right, so state that rights in it belong to the client regardless of who drafted the first version. Without this, handing the interface to another vendor can require extra negotiation. How such rights are framed differs between jurisdictions, so have your counsel draft the clause for the law governing the agreement.
Service levels in a separate schedule. As noted, OpenAPI does not describe response times or availability. Those belong in a service level schedule that references the contract’s operations.
This package changes the conversation about change requests. Instead of “was this in scope?”, the question becomes “does this conform to the approved version of the contract?”, and a tool answers it rather than a negotiation. How to price each interface before it goes into the agreement is covered in how to price an API integration project.
One practical point: these provisions should go into the agreement with every vendor in the same wording. If one vendor’s contract makes conformance an acceptance criterion and another’s does not, then in a dispute over an interface mismatch only one side will be obliged to adapt.
What does API governance look like when it does not turn into bureaucracy?
API governance sounds like a committee that meets monthly and blocks changes. It does not have to be. On a multi-vendor project, governance is simply the answer to three questions: which rules apply to every interface, who checks they are followed, and who settles disputes.
A style guide. One document with rules shared by all interfaces: path and field naming conventions, date and amount formats, the error model, pagination, versioning rules. You do not need to write it from scratch. Public guidelines such as Zalando’s are a good starting point that the client adapts to its own situation. What matters is that the guide exists before the first vendor starts writing specifications, because every vendor will arrive with its own habits.
Automated checks. Everything a machine can check is checked by a linter in the CI pipeline on every specification change. People review only what a machine cannot judge: whether the data model makes business sense, whether an operation duplicates an existing one, whether names are clear to consumers.
Consumer review. Every specification change goes to the teams that consume the interface. This is the cheapest moment to catch a mismatch, because it concerns a file, not the code of three companies.
Dispute resolution. When the service provider and a consumer disagree, the client’s architect decides within an agreed time. Without that role, interface disputes are settled by whoever is more stubborn or holds the stronger contractual position.
Governance built this way costs a few hours of the architect’s time each week and a few minutes per change on the vendors’ side. By comparison, one interface mismatch discovered in end-to-end testing before launch typically costs days of work across several teams. That ratio is not a research finding but simple arithmetic: reviewing a file is cheaper than changing code in several companies.
What does linting check, and why must the rules exist before the first vendor starts?
Linting a specification means automatically checking an OpenAPI or AsyncAPI file against a set of rules. The most popular open-source tool is Spectral, from Stoplight, released under the Apache 2.0 licence. Spectral lints OpenAPI documents (from 2.0 to 3.x), AsyncAPI and Arazzo, and lets you define your own rulesets, in effect writing your style guide in a form a machine can execute.
Rules fall into two groups. The first is correctness: does the file conform to the standard, do schema references resolve, do examples match their schemas, does every operation have an operationId. The second is the client’s style: do paths follow the agreed naming convention, does every operation describe error responses in the agreed format, are amounts sent the agreed way, does every operation have a security scheme.
Why must the rules exist before the first vendor starts? Because a linter introduced halfway through a project reports hundreds of warnings on specifications that are already implemented. Every fix is then a contract change that has to roll out across several vendors. In practice that ends with rules being switched off or existing interfaces marked as exceptions, and the style guide applying only to new work. The same ruleset introduced on day one costs a handful of fixes in the first specification file.
The ruleset should live in the client’s repository next to the specifications and run in a CI pipeline that blocks merging any change that breaks the rules. Vendors can run the same ruleset locally before raising a change. Human review can then focus on substance, not on whether someone used a different casing for a field name.
How do you change the contract mid-project without blocking anyone?
The contract will change. Requirements mature, teams discover edge cases, the business adds features. API-first does not assume a specification is written once and for all, only that every change goes through it in a controlled way.
The key distinction is between backward-compatible and incompatible changes. Adding an optional field to a response usually does not break existing consumers. Removing a field, changing its type, adding a required request field or changing the meaning of an error code does. Leave the judgement to a tool. Oasdiff is a command-line tool that compares two versions of an OpenAPI specification and detects changes that break existing clients. It runs in CI, including as a GitHub Action, and can block an incompatible change before it is approved.
The change process on a multi-vendor project can look like this. The service provider raises a specification change in the client’s repository. The CI pipeline runs the linter and a comparison against the previous version. If the change is compatible, it goes to a quick consumer review and can be approved within days. If it is incompatible, it needs an impact assessment: which consumers are affected, how much work adapting means for them, whether the change can be staged (new field alongside the old one, a transition period, then removal of the old field). The client approves the decision and the split of cost.
Version numbering and deprecation that give consumers time to react are covered in our article on semantic versioning for APIs and libraries. With several vendors I would add one thing: the transition period for an incompatible change must follow the schedule of the slowest consumer, not the fastest. If the integrator releases quarterly, it sets the minimum time the old interface version has to keep working.
How do you accept an interface from a vendor when conformance is the acceptance criterion?
Acceptance on an API-first project rests on one question: does the implementation do what the approved specification promises? Much of that can be answered automatically, which is the main advantage of this approach over acceptance based on a feature demo.
Verification has several layers. The first is response conformance with the schema: a validation proxy (Prism in proxy mode, for example) passes test traffic to the real implementation and flags every response that does not match the specification. The second is contract testing, where consumers record their expectations of a service and the service is checked against them; the method is explained in our glossary entry on API contract testing, and implementation is covered in our article on contract testing and API compatibility. The third is business flow testing against real implementations. The fourth is verification of the service level schedule: response times and behaviour under load.
The table below brings together the artefacts of an API-first project with several vendors, showing who is responsible for what and how to check that each artefact does its job.
| Artefact | Prepared by | Approved by | How it is checked | Acceptance criterion |
|---|---|---|---|---|
| API style guide | Client’s architect | Client | Review before the first vendor starts | Linter ruleset in the repository |
| OpenAPI specification of a service | Service provider | Client’s architect after consumer review | Linter in CI, substantive review | No linter errors, approved review |
| AsyncAPI channel specification | Client (channels and messages), vendors (operations) | Client’s architect | Linter in CI, review by senders and receivers | Shared channel definitions, approved review |
| Mock server | Client or service provider | Client | Availability in the shared environment | Responses match specification and examples |
| Contract change | Service provider | Client after impact assessment | Version comparison in CI, consumer review | No incompatibility, or an approved transition plan |
| Service implementation | Service provider | Client at acceptance | Validation proxy, contract tests, flow tests | Zero mismatches against the approved version |
| Service levels | Client with vendor | Client | Performance tests, monitoring | Values from the schedule for operations referenced by operationId |
These criteria do not replace business acceptance, the check that the system does what users need. But they separate two questions that multi-vendor projects often blur: did the vendor deliver what it promised in the contract, and was the contract well designed? A tool answers the first. The client answers for the second, because it approved the specification. That split is fair to vendors and protects the client from paying twice for a design error.
When is API-first not worth it?
I am defending the thesis that with several vendors, API-first with a client-owned specification is a necessity. I am not claiming it always fits. There are situations where the cost outweighs the benefit.
One team, one consumer. When the same team builds a service and its only consumer and releases them together, agreeing a specification before code is a team talking to itself. A specification generated from code, plus tests that stop it drifting, is enough.
A throwaway prototype. If a few weeks of work are meant to test an idea and the code will be discarded, a formal contract slows the experiment. Just be honest about whether the prototype really will be discarded, because prototypes have a habit of reaching production.
An interface imposed from outside. When you integrate with an external system whose API you do not control, such as a bank, a government service or a packaged software product, you do not design the interface, you accept it. API-first then makes sense only for the layer you build between that system and your own applications.
No capability on the client side. A model in which the client approves specifications needs someone who can judge them. If there is no such person and there will not be, approval becomes a formality and accountability blurs even more than without API-first. In that case, secure the capability first rather than introduce a process nobody will genuinely run.
The line is simple: API-first pays off more the more independent teams and companies consume the same interface and the longer that interface is meant to live. With two vendors it starts to pay. With three or more, it is hard to run the project without it.
Where do you start if a multi-vendor project is already under way?
Not everyone reads this before a project starts. If vendors are already working and specifications are generated from code or not written at all, you can still move to API-first, just gradually.
Step one is an inventory of the interfaces between vendors. Not every interface in the system, only those connecting parts built by different companies. There are usually fewer than you expect, and they are the ones generating disputes.
Step two is generating specifications from the existing implementations and moving them into the client’s repository. A generated file is not ideal, but it is a baseline. From then on the rule is that every interface change starts with a specification change in that repository.
Step three is a linter with a lenient ruleset covering correctness and the most important style rules, with exceptions for existing deviations. Tighten the rules with each new interface version.
Step four is version comparison in CI to block accidental changes that break consumers. This is often the quickest win, because it removes the most expensive kind of mismatch.
Step five is updating agreements at the next opportunity: an amendment, a new stage or a renewal. Introduce the provisions on conformance as an acceptance criterion and on the change procedure into all agreements at once.
What are the key takeaways?
On a project where several companies deliver the software, the most important technical document is not the architecture or the test plan, but the contract for the interfaces between their parts. API-first is a way to make that contract exist before the code, be precise and belong to the party that bears the cost of every mismatch.
Remember six things. First, the client owns the specification: the service provider designs it, consumers review it, the client’s architect approves it, and the file lives in the client’s repository. Second, the contract must settle types, formats, errors, security and examples, and requirements OpenAPI does not describe go into a service level schedule. Third, use AsyncAPI for event-driven communication and define shared channels and messages in one place. Fourth, a mock server generated from the specification lets teams work in parallel from the second week of the project. Fifth, introduce the style guide and linter before the first vendor starts, and configure version comparison in CI to block incompatible changes. Sixth, write conformance with the approved contract version into the agreements with every vendor, in the same wording, as an acceptance criterion.
If you are planning a project where interfaces will connect several vendors, or want to bring order to one that is already running, see how we work in custom software development, including API development and systems integration, or book a call. We can provide a team that builds a service to your contract, or, on a project where we build none of the parts, an architect who helps you draft that contract and keep it on your side. The basics of the discipline are summarised in our glossary entry on creating APIs.