API Versioning is Live

[AdWordsAPIAdvisor]

We are excited to announce that we have launched global support for API
versioning.

This afternoon we released version 3 of the AdWords API. The AdWords
API v3 contains new support for Content Bidding.

So what is changing?

First and foremost, this should reduce the need for you, our
developers, to conduct just-in-time upgrades based on our release
schedule. When a new version of the AdWords API is released, we will
continue to support the old version of the API for 4 weeks before
deactivating it. This four week period provides you with a full month
to familiarize yourselves with the new WSDL, test changes, and update
your production code.

Therefore, the version that everyone is running today (Version 2), will
be deactivated in four weeks on February 22, 2006. All developers
running v2 should make sure that they upgrade to v3 by this date. As a
precaution, a warning will be posted to the Blog
(http://adwordsapi.blogspot.com), Forum and API Announcements email
list
(http://www.google.com/support/adwordsapi/bin/answer.py?answer=26085)
one week prior to deactivation of v2.

Secondly, we've added a "release notes" section
(http://www.google.com/apis/adwords/developer/ReleaseNotes.html) to the
Developer's Guide
(http://www.google.com/apis/adwords/developer/index.html). This will
help bring you up to speed on the latest changes and differences
between the versions.

And finally, the Developer's Guide has been updated to display full
details for all supported versions, as well as the diffs between them.
By default, the pages you view will display information for the latest
version. However, you can now toggle your view between versions by
clicking on the links that we've added to the upper right-hand corner
of the Developer's Guide.

So what version are we on now?

The version that you have all been using for the last several months is
"Version 2". The new version that we have released today is
"Version 3". If you ever have any doubt as to what version you are
using, you can always determine the version number by examining the web
services URL that you are currently using.

Today you are using:
-- https://adwords.google.com/api/adwords/v2/ServiceNameService?wsdl
(note the "/v2/" in the middle of the URL).

When you re-code for the latest version, you will have to change this
URL to:
-- https://adwords.google.com/api/adwords/v3/ServiceNameService?wsdl.

What should we do if we have questions?

We feel strongly that our new versioning system will make testing and
upgrading easier and more stable for all. However, we do understand
that this is also a big change. Therefore, Patrick, our API
Evangelist, will be paying extra-close attention to your versioning
posts on the AdWords API Forum for the next few weeks.

And, as always, please feel free to check our API Help Center
(http://www.google.com/support/adwordsapi/bin/topic.py?topic=8400) for
more information on Versioning.

We hope you find this new versioning system helpful and thank you again
for your support of the AdWords API.

-- Rohit Dhawan, Product Manager

[ma...@znep.com]

AdWordsAPIAdvisor wrote:
> We are excited to announce that we have launched global support for API
> versioning.
>
> This afternoon we released version 3 of the AdWords API. The AdWords
> API v3 contains new support for Content Bidding.
>
> So what is changing?
>
> First and foremost, this should reduce the need for you, our
> developers, to conduct just-in-time upgrades based on our release
> schedule. When a new version of the AdWords API is released, we will
> continue to support the old version of the API for 4 weeks before
> deactivating it. This four week period provides you with a full month
> to familiarize yourselves with the new WSDL, test changes, and update
> your production code.

That is great news.

4 weeks, however, is way too short a turnaround time. Having to do
fire drills every time a new API version comes out, figuring out what
the changes are and how they impact things, integrate making the change
into the product development cycle, get it through QA and get software
out in less than 4 weeks isn't very friendly.

A "full month" isn't long when the use of the API is one small part of
a much bigger product.

A more reasonable timeframe might be 3 months.

[Peer Jakobsen]

This is really good news.

I think you used a little to much strikethrough in the release notes
though (maxContentCpc and networkTypes):

http://www.google.com/apis/adwords/developer/ReleaseNotes.html)

[JezC]

For production purposes, every organisation for which I've done
corporate targeted software has required a maximum of two releases per
year. The type of software I've worked has required support for old
versions from between a year to twenty years.

One month may be acceptable for a beta program. It's not workable for
most commercial organisations in a production environment. If one has
clients, using the interface that results, they also have training
needs, and just getting all the right staff into the right meeting with
training documentation can take a whole month, after the software is
developed and run through QA and handed over to the client's IT group.

Please tell me that this one month notice is just for the Beta period.
It needs to be closer to three months, as a bare minimum and six months
as a reasonable period.

Cheers, JeremyC.
--
Merjis : web marketing technology services and consulting :
http://merjis.com/

[Jon Tara]

JezC wrote:

> One month may be acceptable for a beta program. It's not workable for
> most commercial organisations in a production environment.

Ditto.

I've worked extensively with data feeds and order-entry systems in the
financial industry. It would be unheard of not to provide a year of
overlap when releasing a new, incompatible API.

However, they generally try to avoid releasing incompatible versions.
When they do, that is a MAJOR event. In addition to running the
previous version side-by-side for a year, test servers are always
available, and usually made available some from (from weeks to months)
prior to the new API going live.

I do see a problem with the versioning scheme. It provides no
distinction between compatible changes/extensions and incompatible
changes. More typically, a major/minor numbering scheme is used, where
the minor number represents a compatible extension to the API.

[Patrick Chanezon]

Thanks Jez and Jon, we'll definitely take this feedback into account.
Jon, about the minor/major versioning scheme, I think it is not that big an issue with an online web service like this, as long as we provide enough details in the release notes about what changes.

P@

--
Patrick Chanezon, AdWords API evangelist
http://blog.chanezon.com/
http://www.google.com/apis/adwords/

[Robert]

4 weeks are too short. Please imaging, a DirectX 9 game will still run
the next 4 weeks if DirectX 10 is released ;-) Nobody would have a
motivation to develop a DirectX game.
In 4 weeks I have to adjust or recreate my API client and install+setup
it on the computer of my clients. How about my vacation, sickness,
other urgent projects?

[Robert]

[Ed Hennis]

All of the v3 API URLs are returning 404.

[Darrin]

Ya, I have to add my voice to the chorus here...

In an ideal world where I don't have to do any other development work,
1 months notice would be fine... but we all know that's not how the
real world is.

We plan all our work on a quarterly basis. That means I need to know
about it at the beginning of Q1 if it's going to happen in Q2. Anytime
past mid Q1 and it's not going to get done till Q3. What this means
that 6 months is really the minimum time frame you should consider
keeping old versions alive. 9 months would be more accomodating :-) .

Thanks,
Darrin