Question

When ever I hear discussions on releasing version 1 APIs it’s always accompanied by this genereal idea:

We can’t release our API yet because we have to get it right the first time.

Here’s a recent example by Vic Gundotra, but there re numerous others including Stackoverflow itself, back in the day before the API was released.

What I don’t understand is, why does the first version have to be so “right”? With APIs you can implement versioning and good documentation, and if you do that well, which isn’t that hard to do, why be so precious about the version 1 API?

From version to version, because it’s versioned, the API can change dramatically without any breaking changes, since the old version is still supported. I was wondering why the big issue about releasing APIs..?

Answer 1

From version to version, because it’s versioned, the API can change dramatically without any breaking changes, since the old version is still supported.

That means two things:

• Maintaining multiple versions of an API. Even if you only support “the last 3 versions” that’s still a burden. In particular, if you expose a feature you want to remove later on, it means you can’t do any of the clean-up which would be available as part of the removal until N more versions have come and gone. Consider any ramifications on stored data that may come about due to significant changes in the API – migrating storage representations when they’re used by multiple systems, updated on different release schedules, is a real pain. (Yes, there’s a difference between implementation and API – but changes in API often end up meaning changes all the way through the stack.)
• Eventually irritating a lot of developers. Even if you give plenty of warning, people will get annoyed if they have to do significant rewrites because version 1.0 was rubbish and when 1.4 comes out, 1.0 will be removed.

Designing an API correctly is a tricky business. Yes, there’s a balance to be struck between pragmatism and perfectionism – but it’s not nearly as simple as you’re making it out to be.

I’d also point out that there’s a pretty big maintenance difference between (say) an open source project with 10 users putting something out quickly then changing it, and a company like Google or Microsoft doing so for a global developer community. There’s even a big difference between an internal API at a big company (where you can’t easily fix the whole codebase) and an internal API at a small company where you get to change the world whenever you want.

I have some sympathy for the astonishment about making such a big deal about it – but that suggests you haven’t experienced the pain that shifting an API can mean. You might be equally astonished – or even more so – at just how hard it can be to make fundamental changes once a bad decision has escaped into the world.

(Disclaimer: I work for Google, but not in the G+ area. The opinions in this answer are my own, and don’t represent Google.)