Sid Maestre from APIMatic: APIs build vs buy
Sid Maestre says skip the operation ID in your OpenAPI spec and a code generator will guess a name like 'postChocolate' for you. Bother to name it 'createChocolate' yourself, and that's exactly the kind of detail that separates a good generated SDK from an unusable one.
Sid Maestre spent years in developer experience at Xero and PayPal before joining APIMatic, a platform for generating SDKs and documentation from OpenAPI specs, where he also hosts The Art of Developer Experience podcast.
We get into when it actually makes sense to build your own SDKs versus buying or going open source, the specific OpenAPI hygiene that determines whether generated code is any good, and how AI is starting to change what a documentation chatbot can actually do — synthesizing working integration code from a company's own generated SDKs, rather than just answering questions from a knowledge base.
The Q&A below is experimental — extracted from the episode transcript with AI. If you spot a mistake, let us know at jack@scalingdevtools.com.
What's the actual case for platforms like Xero investing early in a developer ecosystem?
Before a lot of these applications moved from desktop to the cloud, moving data in and out of desktop accounting software meant wrestling with clunky import/export menus — it was slow and time-consuming. APIs unlocked doing that in real time, reliably. The team that founded Xero was forward-thinking about that — they saw what was happening with platforms like Salesforce and treated it as an opportunity to disrupt the incumbent accounting software with an ecosystem of partners building add-ons on top of them, rather than trying to build every feature themselves.
What's the trade-off of building a business on top of someone else's platform, like a Shopify app or a Xero add-on?
The company running the platform has to be genuinely successful with its core product for there to be a large enough audience for developers to benefit from — and that audience is the real attraction, since building a dev tool from scratch means you have to go find or create your own audience, which usually isn't an engineer's strong suit. The trade-off is you have to play by the platform's rules and terms of use, and there's a real risk: if the platform later adds a basic version of what you built as a feature, you can become irrelevant overnight. At Xero, we saw this cut both ways — when we added basic inventory functionality, our existing inventory app partners weren't hurt, because they went so deep on the complexity of multi-channel, online/offline inventory management that our basic feature didn't compete with what they offered. Knowing exactly how deep and meaningful your value is to customers is what gives you security against the platform eventually encroaching on you.
How should a company think about build versus buy for their own API's developer experience?
We all respect what Stripe built, and they've said themselves they built SDKs to reduce the boilerplate code developers have to write and maintain — but that's been built in-house over a long time with, I'd imagine, millions of dollars of investment. Whether you should aim for that depends heavily on your stage: you need to hit product-market fit with your APIs first, have great documentation, and a way to onboard your first hundred developers, before you're ready to think about matching Stripe-level DX. It also depends on how much control you actually need — do you need to control every line of code in the libraries you hand developers? Stripe seems to have that as part of its DNA, but that requires hiring language experts and continuously investing resources most companies don't have, especially when engineers are already stretched thin between building product features and building internal tooling like a custom docs CMS.
You've described build, buy, and open source as three different options. How do those actually differ in practice?
Building everything yourself gives you full control but costs the most ongoing engineering time. Going commercial — a platform like APIMatic — means you're effectively hiring a team of people thinking full-time about SDKs and documentation, at the cost of waiting for them to ship what you need, though you can push to get things prioritized on their roadmap. Open source splits the difference: it's technically free, but you're both buying into an existing ecosystem — with its direction, its features, its bugs — and building, because you still need engineers to maintain that toolchain in-house. I've worked with the OpenAPI Generator project myself, modifying templates and getting deep into Mustache templating, going back and forth with the community on things like PHP output when we weren't PHP experts ourselves.
What's the actual cost of not giving developers an SDK at all?
Two things, mainly. First, support load — without a library, developers roll their own solution from scratch, and anything even slightly unusual, like non-standard authentication or uploading binary data through multipart forms, can eat hours of their time over something as small as a malformed header, versus a tested library that's known to work. Second, time to production: a commercial SDK gives you retries, timeout handling, circuit breakers, and everything else a robust integration needs out of the box, and without it, developers building something they're putting in front of their own customers have to build and maintain all of that machinery themselves. If it takes six to nine months to get a production-grade integration built instead of a few weeks, that's real revenue you're not collecting from a high-volume customer or partner in the meantime.
What's the one thing you'd tell someone about to write their first OpenAPI spec?
Make sure it's well linted and validated for what you actually intend to use it for, because a totally valid OpenAPI spec can still generate bad code. If your linter doesn't require descriptions or examples, you might not end up with the examples you need to generate tests. If you skip the operation ID on an endpoint, the generator will infer a name for you — something like 'postChocolate' when what you actually wanted was 'createChocolate' — and that shows up directly in the readability of the generated library's methods. There are open-source tools like Spectral, originally built by Spotlight, and ReDoc's linting tool for exactly this. APIMatic also built a VS Code extension with about 1,200 linting rules specifically for spec quality — it's free regardless of whether you end up using APIMatic itself, so it's worth opening your own spec in it just to see how close you are to generating good code.
How is AI actually changing how companies build documentation and support tools around their APIs?
The first year of broad AI usage around APIs, results weren't great — a lot of experiments that didn't quite work. The second year has gotten noticeably better: tools that help generate an initial OpenAPI definition, or fix an existing one, and on the documentation side, chatbots trained on a company's docs, forums, and support tickets. At APIMatic specifically, because we already generate SDKs, code examples, and guided walkthroughs, our approach is to have the AI synthesize working code that doesn't exist anywhere yet — importing from our actual generated libraries and stitching together two, three, four API calls into integration code a developer can copy straight into their IDE and run, rather than just answering a question from a knowledge base.
Do you think AI coding tools are actually good enough yet for professional developers, not just hobbyists?
I think of it like the early days of WYSIWYG HTML editors — tools like Microsoft FrontPage looked amazing in a demo because what-you-see-is-what-you-get, but the actual code it spat out was a nightmare. It wasn't until Dreamweaver let you toggle between the visual editor and the code itself, tweak either one, and see it update live, that the tooling matured. I think AI coding tools are heading in that same direction — more ability to jump between the AI output and the code itself and iterate on it — and it's still improving fast. I wouldn't judge today's AI coding tools by what they could do a year ago, the same way you wouldn't judge modern web tooling by FrontPage.