Latest / B2B SaaS Talks with Fexingo: Enterprise Software, Sales Cycles, and Procurement / Enterprise Buyers Now Demand a Vendor OpenAPI Specification
Transcript
- Lucas: Luna, I just saw a procurement term sheet from a Fortune 500 energy company — one of the big integrated players in the Gulf — and buried on page 14 of their vendor addendum was a clause I hadn't seen before. It reads, quote, 'Vendor must provide a valid OpenAPI 3.1 specification for all customer-facing APIs within thirty days of contract signing.' Not optional. Not 'upon request.' Mandatory. Luna: Thirty days is aggressive. Most enterprise SaaS companies I talk to say their API documentation is six months out of date before they even close the first deal. Lucas: Exactly. And that's the whole point. This buyer — let's call them GulfCo — had just walked away from a two-point-four-million-dollar deal with a data-integration startup because the startup's REST API had seven undocumented endpoints that the buyer's security team discovered during a routine dynamic scan. Luna: Seven undocumented endpoints. So the buyer knew more about the vendor's own API surface than the vendor's sales engineers did. Lucas: Exactly right. The startup's argument was, 'Our docs are good enough for our existing customers.' But GulfCo's CTO told me — off the record — 'If you can't describe your own API in a machine-readable format, you don't understand your own attack surface.' That's the new baseline. Luna: It's not just security though, right? The OpenAPI spec also serves as a contract between the vendor and the buyer's integration team. It tells you exactly which endpoints exist, what payloads they expect, what status codes they return. Lucas: Right. It turns API documentation from a PDF that rots on a SharePoint site into a single YAML or JSON file that a buyer can validate programmatically. GulfCo's procurement team now runs every vendor spec through an automated linter that checks for things like missing error responses, undefined security schemes, and endpoints that return a 200 when they should return a 201. Luna: So they're essentially treating the OpenAPI spec like a bill of lading. If the manifest doesn't match the cargo, the container doesn't get loaded onto the ship. Lucas: That's the analogy I've been looking for. And it's spreading. I've now seen similar language in procurement RFPs from three of the top ten US banks, two major healthcare systems, and at least one big-box retailer that's been aggressively building out its marketplace platform. Luna: What about the vendor side? If I'm a startup with a legacy REST API that was built in 2019 and never really documented, how painful is it to produce an OpenAPI 3.1 spec on a thirty-day timeline? Lucas: It ranges from 'moderately annoying' to 'genuinely expensive.' For a well-structured API that already follows REST conventions, you can auto-generate a reasonable first pass using tools like Swagger Inspector or APIMatic in a few hours. Then you hand-edit the descriptions, add the examples, and you're probably looking at two to three days of engineering time. Luna: But for the startup that cut corners — the one with the seven undocumented endpoints — that's a different story. Lucas: Totally different. If your API has inconsistent naming conventions, resources that respond in XML sometimes and JSON other times, or endpoints that behave differently depending on the customer's IP address — which I have actually seen — then retrofitting an accurate spec is essentially a refactoring project. That's weeks, not days. And it's the kind of technical debt that kills deals. Luna: And if a vendor refuses to provide the spec outright? I've heard stories of companies saying, 'Our API is proprietary, we can't share the spec.' Lucas: That's increasingly a dealbreaker. The buyer interprets it as the vendor hiding something — either the API is so brittle that an honest spec would scare people away, or the vendor doesn't trust the buyer enough to share basic integration documentation. Either way, the procurement committee flags it as a risk. Luna: So this is really about trust and symmetry of information. The buyer is saying, 'I need to know exactly what I'm plugging into my infrastructure before I sign the contract.' And the OpenAPI spec is the most efficient way to provide that transparency. Lucas: And it's not just about security. The spec also lets the buyer estimate integration cost more accurately. I talked to a VP of engineering at a mid-size logistics firm who said that before they required OpenAPI specs, their integration estimates were off by an average of forty percent. Now they can run the spec through a code generator, get a working SDK in the language of their choice, and have a prototype integration running in a day. Luna: Forty percent — that's huge. That's the difference between a project getting approved or getting killed. Lucas: Right. And the same VP told me that their procurement team now has a standard clause that says, 'If the vendor's OpenAPI spec is inconsistent with the actual behavior of the API, the buyer may withhold payment until the spec is corrected.' That's essentially turning the spec into a legally enforceable representation of the product. Luna: That's interesting — because it's not just a technical document anymore, it's a contractual document. And if the spec says an endpoint returns a 200 on success, but the actual API returns a 202, the vendor is technically in breach. Lucas: Which is exactly why some general counsels are now asking for the OpenAPI spec to be included as an exhibit to the master service agreement. I've seen two instances in the past quarter where a vendor's legal team pushed back on that — arguing that the spec is 'illustrative, not definitive' — and the buyer simply walked. Luna: And these are not small deals, I assume. Lucas: No. The smallest one I heard about was a seven-figure annual contract. The buyer's position was, 'If you're not willing to stand behind your API documentation, how can we trust your uptime SLA?' Luna: So this OpenAPI requirement is becoming a signal of overall vendor maturity. If you have a clean, accurate, machine-readable spec, it suggests you also have good testing, good versioning, good deprecation policies. Lucas: Exactly. It's a proxy. And procurement teams love proxies because they compress due-diligence cycles. Instead of sending a twenty-page API questionnaire and waiting two weeks for answers, they can run the spec through a linter in five seconds and get a score. Luna: Speaking of proxies — and this ties back to something you said earlier about the bill of lading — I wonder if we'll start seeing procurement teams requiring the vendor to maintain a public OpenAPI registry, not just deliver a file once. Lucas: I think that's coming. In fact, the same GulfCo addendum I mentioned earlier includes a clause that says the spec must be updated within five business days of any API change that affects the contractually agreed functionality. So it's not a one-time deliverable — it's a living document. Luna: And if the vendor has a continuous deployment pipeline that pushes changes multiple times a day, that five-day window could get tight. Lucas: It does force the vendor to either slow down their release cadence or invest in automated spec generation as part of the CI pipeline. The more sophisticated buyers know this and they're okay with the vendor choosing the latter — because it means the vendor has engineering discipline. Luna: So this is really a story about how a technical standard — OpenAPI — is being repurposed as a procurement and risk management tool. It's not about the spec itself, it's about what the spec represents. Lucas: Exactly. And it's a reminder that in enterprise SaaS, the line between technical documentation and legal contract is getting thinner every quarter. If you're a B2B founder listening to this and you don't have an OpenAPI 3.1 spec for your product yet, you're already behind. Luna: And if these kinds of conversations are useful for what you're building or running, we'll keep digging into them. Listener support is what keeps this show free and independent — no ads, no sponsors. If that matters to you, the best way to help is buying us a coffee. It's buy me a coffee dot com slash fexingo. Just a simple way to say the show is worth your time. Lucas: Appreciate that. So let's zoom out for a second — because I think there's a bigger pattern here. The OpenAPI mandate is part of a broader movement where enterprise buyers are demanding that vendors provide what I'd call 'auditable interfaces' for everything — not just APIs, but also security controls, AI model behavior, data lineage. Luna: Right. We've seen the same thing with SOC 2 Type II reports becoming table stakes, and with AI model cards and bias audits becoming common in RFPs. Lucas: Exactly. The underlying principle is: 'Show me, don't tell me.' Buyers no longer trust vendor slide decks or sales engineers who say 'trust me, it works.' They want a machine-readable artifact that they can independently verify. Luna: And in the case of OpenAPI, the technology is mature enough that there's really no excuse for a vendor not to provide it. The OpenAPI Initiative released version 3.1 back in 2021, and the tooling ecosystem — from code generators to linters to mock servers — is incredibly robust. Lucas: So what's the pushback? I've heard some vendors say, 'Our API is a competitive advantage, and sharing the spec would let competitors copy our interface design.' Luna: That argument doesn't hold much water. Your API's job is to be useful, not to be secret. If your competitive moat is the fact that competitors can't figure out your endpoint structure, you don't have a moat. Lucas: Completely agree. The real competitive advantage is in the data your API surfaces, the business logic behind it, and the quality of your integration support. Not in obscurity. Luna: And customers know that. Which is why they're adding this clause. It's not about being difficult; it's about reducing risk and speeding up procurement. Lucas: So if you're a SaaS founder listening, here's the concrete takeaway: before your next enterprise RFP lands, make sure you have an OpenAPI 3.1 spec that is accurate, complete, and ideally auto-generated from your actual codebase. Run it through a linter yourself. Fix the warnings. Then treat it as a living document that you update with every API change. Luna: And if you're a buyer, consider adding the clause we discussed. It's a small change to your procurement template that can save weeks of integration headaches. Lucas: The interesting question for me is what comes next. If OpenAPI specs become standard in procurement contracts, will we see buyers demanding the same for event-driven APIs? AsyncAPI is the emerging standard there. Luna: I think it's inevitable. And then maybe GraphQL schemas too, for the vendors that offer GraphQL endpoints. Lucas: So the trajectory is clear: more machine-readable contracts, less human-interpreted documentation. The machines are becoming the auditors. Luna: And that probably saves everyone time in the long run. Even if it means a few uncomfortable weeks for vendors who have some cleanup to do.