These past two weeks I’ve invested a lot more time than I intended to in migrating from the community APIs to the game data / profile APIs. I don’t want to complain but I do want to better understand what level of promise Blizzard thinks it is making when it offers an API, and what I should expect for the future stability and value of my development investment.
To me the implied promise of an API is that it represents a safe platform on which to build application logic and code. This doesn’t mean unchanging, because things always change. But to me it does imply a certain level of care of making change in the most gradual way possible; of providing strong documentation of what is changing; and providing as much notice as possible.
I personally don’t feel the recent API changes have included the same level of impact mitigation, clear documentation, and ample notice that I’m used to from other projects.
I’m not talking about the straight forward stuff like a different URL or breaking one big chunk into several smaller chunks. That’s not going to break a lot of code.
But I have had breakages from more fundamental changes made seemingly casually and with no particular notice of the change, either from the old API to the new, or even from new to new overnight as more changes are made. Things like switching ID spaces without providing translation tables, or using the same or similar property name for a significantly different interpretation of the same underlying game state.
I recognize the API team is under the gun right now and I don’t want to do anything but thank those involved for doing the best they can. But can we have a discussion for what level of stability and change documentation we can expect after the new APIs are launched next month?
For example, is the lack of explicit documentation about big changes to what a field means because there was no time to do it, or because the feeling is that developers should just notice it and reverse engineer it and fix it on their own, all while their application is live?
What does an id mean to Blizzard? Is it intended to be a long term stable identifier that can be used overtime within and even across multiple developers (my personal assumption?) Or are we not to rely on that, and treat it as a private transitory token valid only for a single user request?
I’ve kind of rambled on too long so for a TLDR version my request would be that:
ids are changed only when unavoidable and translation is always provided
any change to the significance of the data returned by the same API / property be documented and hopefully provided in advance, or at minimum as the code change goes live on the servers.