CODEWITHSUNDEEP
apiarchitectureversioningasp.net-web-api
andy
andy

Reputation: 8875

Why are developers so precious about releasing APIs when you can implement versioning?

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..?

Upvotes: 6

Views: 299

Answers (3)

Jon Skeet
Jon Skeet

Reputation: 1500893

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.)

Upvotes: 8

Martin James
Martin James

Reputation: 24857

You could maybe ask for an extendable API, eg:

APIclass::anAPIcall(Xclass Xparam, Yclass Yparam, void *userData, void *extensions);

.. where 'extensions' is passed as Null in V1.0.

You could agree with the vendor that the functionality provided by V1.0 will not be supported, (but will continue to be provided), in later releases.

Upvotes: 0

Friedrich
Friedrich

Reputation: 6006

I think this is a bit hard to answer. But let me try. You do your programmming, but did you get it mostly right the first time?

Well my experience is that I start with some method and indeed it grows. After the tests are green I look at it and found it not good enough. I'm adding other methods I'm trying to "clean" it.

Now a API for a larger software package, is not that "small" at all. And I bet you do not even get near something you find "good" enough, right from the start. However if you release an API you'r bound to it. You will not make many friends breaking APIS as you go. So if you are somewhat serious about your code you will support the different versions.

I suggest to have a look into the history of GTK. there is GTK 1.2.x and things beyond 2. We once wrote software according to GTK 1.2 and were not "happy" as 2 was coming out not compatible with 1.2. And so the software still sticks in 1.2.x of GTK...

So not the usual way is not that you have still an olde API running but have it broken. And therefor, programmers are not that happy to realease an API very early (IMHO)

Upvotes: 2

Related Questions