Why are developers so valuable in releasing an API when you can implement version control?

Question

When I hear discussions on the release of version 1 APIs, it is always accompanied by this genetic idea:

We cannot release our API yet, because we must do it right the first time.

Here's a recent Vic Gundotra example, but there are many others, including Stackoverflow, the day before the API is released.

I don’t understand why the first version should be “correct”? With APIs, you can implement version control and good documentation, and if you do it well, it's not so difficult to do, why are version 1 APIs so valuable?

From version to version, as it is being versioned, the API can change dramatically without any changes, as the old version is still supported. I was wondering why there is a big problem with the release of the API.?

Answer 1

From version to version, as it is being versioned, the API can change dramatically without any changes, as the old version is still supported.

This means two things:

• Support for multiple versions of the API. Even if you only support the “last 3 versions,” which are still a burden. In particular, if you expose a function that you want to delete later, it means that you cannot perform any cleanup that will be available as part of the deletion until other versions appear and disappear. Consider any implications for stored data that may result from significant changes to the API — moving storage views when used by multiple systems updated in different release schedules is a real pain. (Yes, there is a difference between the implementation and the API, but changes to the API often end up with all changes happening through the stack.)
• In the end, a lot of developers are annoyed. Even if you give a lot of warnings, people will get annoyed if they have to do serious rewrites because version 1.0 was garbage, and when 1.4 comes out, 1.0 will be deleted.

Designing the right API is a complex business. Yes, there is a balance between pragmatism and perfectionism - but it’s not as easy as you do it.

I would also note that there is a rather big difference in service between an (say) open source project in which 10 users quickly post something and then change it, and a company like Google or Microsoft, for the global developer community. There is even a big difference between the internal API in a large company (where you cannot easily fix the entire code base) and the internal API in a small company, where you can change the world whenever you want.

I have some sympathy for the amazement of making such a big deal about it, but it does mean that you have not experienced the pain that an API change could mean. You may be equally surprised - and even more so - how hard it can make fundamental changes after a bad decision has slipped into the world.

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

Answer 2

I think this is a little difficult to answer. But let me try. You program, but did you get it the first time the first time?

Well, my experience is that I start with some method and it really grows. After the tests are green, I look at it and consider that it is not enough. I am adding other methods that I am trying to "clear".

Now the API for a larger software package is not quite "small." And I'm sure you haven't even come close to what you find “good” enough from the start. However, if you release the API you are bound to. You will not make many friends violate APIS when you go. Therefore, if you are serious about your code, you will support different versions.

I suggest a look at the history of GTK. there is GTK 1.2.x and things beyond 2. We once wrote software in accordance with GTK 1.2 and were not “happy” because 2 of them turned out to be incompatible with 1.2. And so the software is still stored in 1.2.x GTK ...

So the usual way is not that you still have the old API, but it is broken. And therefore, programmers are not very happy to repurpose the API very early (IMHO)

Answer 3

Perhaps you can request an extensible API, for example:

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

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

You may agree with the provider that the functionality provided by V1.0 will not be supported (but will continue to be provided) in future releases.