The implied contract of an API

API Discussion
1

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.

4 Likes
2

I’d like to echo Briala’s frustrations with the API migrations. I have also spent way more time updating my site than I wanted, and it feels like there is still so much more to go.

As a programmer, I can certainly put myself in the shoes of Blizzard’s API team, and don’t really fault them for having bugs or that changes have caused unintended consequences for consumers of their API. I’ve had plenty of bugs with every piece of software I’ve built.

But I think what is most frustrating is that the API Bug Report forum is a complete ghost town. I’ve submitted roughly a dozen bug reports with the new APIs, and have not gotten any sort of response from Blizzard. Same with many other users that have been posting bug reports. It would be nice to at least get some confirmation whether our issues are bugs that will be fixed, or if they are intentional design changes that we’re just going to have to work around. The id mappings that Briala brings up is a perfect example of that.

I also think it would have been more appropriate to have the new APIs ready, stable, and bug-free BEFORE asking 3rd party apps to begin migrating. The December 16 deadline has required us to begin updating code before the new APIs are even ready, and it feels like we’re building a plane as we’re flying it. Even if the deadline gets extended, it feels like the damage has already been done, as I’ve already upgraded as many pieces of my codebase that I can while still waiting for other endpoints to be built.

Again, not really trying to point any fingers, just hoping we can start getting some communication and resolution to these issues soon. Thank you!

1 Like
3

Echoing the above.

It’s clear the Community API developers that post here are doing the best they can to get it ready. But there’s clearly significant concern that the API will not be fully working by the deadline and that sites are going to be broken. Whether true or not, it certainly doesn’t feel like sufficient resources are being devoted to getting it done in time, and if so that’s not the fault of the developers.

Regarding the API Bug report forum - I’ve stopped reporting there because it appears that developers are only responding here on the Discussion forum, and thus give the impression that bugs are not being noticed on the former.

1 Like
4

Hi Briala, Shoogen, Wain, and our other Community Developers,

Thank you for the feedback. We’re working on addressing the many points you’ve collectively raised, though understandably there’s a lot to unpack in these posts, and to do it justice that’s going to take a little time.

In short, we hear you. We’re working to do better, and will provide a more in depth response in the near future.

3 Likes
5

Hey again everyone,

While we’re working on the rest of the response, I wanted to start addressing some of the concerns, and gathering more information for us.

Repeated throughout the various posts are concerns about the timeline and breadth of the changes being made and not having enough time to develop and test your own apps with the new changes. From our side, the source of these collective changes that we’re assembling are numerous, ranging from data that doesn’t make sense any more, to a back end tech stack solution, to adjustments for some of the data protection efforts we’re making. Some of those we can push back the date on, others we cannot. We’re working on a list of endpoints that we’re going to delay to provide some more breathing room for you, our community, so look forward to that soon.

As far as the “stability of the APIs”, that’s a moderately ambiguous phrase. If you’ve noticed endpoints being unresponsive, we would greatly appreciate reports of that either in this forum or on the API Bug Report Forum including relevant details. However, if you’re referring to the short timeframe and scope of the changes of APIs, this is a rather unusual change for us as well, and part of the timeline is directly related to things with hard deadlines for us. That hard deadline does not affect all the APIs being removed. Again, look for information in the future about that.

There are many references to generalized pain points, but not citing specific examples of where this pain is occurring. If you could cite specific examples you’re having (ex: Briala, your main concern seems to be with an ID, but no context of which specific endpoint or endpoints).

Regarding the Bug Report forums: providing no response unless we’re asking clarifying questions has been typical, not just of that forum, but all bug report forums for Blizzard. We do read the bug reports. We ingest, evaluate, and prioritize them to get fixed as appropriate. Please continue to use them!

We greatly appreciate the feedback you’ve given thus far, and more information you can provide us, the better we will be able to understand how you’re using our APIs and to accomplish what goals, and how we can better support that.

1 Like
6

Thank you Ralangee for the thoughtful responses. I really appreciate the engagement and helpful attitude.

In my case I didn’t provide specifics because I was sincere that I wasn’t writing to complain about the current situation or ask for a change to the current API. My motivation for this thread is to prevent future similar breaking changes, or at least to have them mitigated better.

I’m worried there may be no way to explain the importance of not changing a primary key without sounding patronizing, so I’ll apologize in advance. But I guess it is fair for me to talk a little bit about how the changes to the ids used for mounts, pets and titles affected my code and my time to migrate.

I could say the ids started to matter to me from the first time I made my first call to the community API, but the truth is they were already important to the ecosystem before that. For example, because the old response for mounts for Brown Horse included spell id 458, I knew immediately I could link to Wowhead using that id and have a tooltip generated for my page and a helpful link available for users who wanted more details.

Then as I worked more on my app and gathered and created more data over time, the ids started to matter for internal linkages across my app. That id is how I know which characters had that mount on what dates, how I kept statistics and timeline data, and how I linked my hopefully value add editorial to it (“Briala rates this mount 3 stars!”).

Now I don’t want to over-exaggerate. Another member here helpfully pointed out there is a table from wow.tools that had both the old spell id and your new mount id. My own efforts before that involved joining on mount name and then manual inspection to clean up the frequent case where the same mount has both an alliance and a horde version with the same name. In doing that it of course it immediately became clear that the old API covers more “mounts” (some really in game effects) than the new one, so I had to spend time reverse engineering why that was and what it means.

If I had it to do over again, I might be able to manage that whole transition in an afternoon. But of course it’s not like that the first time through when you don’t know what’s going on. Figuring out for myself what I just explained above took me time and false starts. In trying to make a mid-stream change I corrupted some of my tables. I eventually rolled back and brought a second migrated app up in parallel which was the right approach for me although time-consuming. All of this jacks up the hours and stress.

In another version of this migration these effects on developer time could have been heavily mitigated with a few simple tweaks. Providing both the old IDs and the new IDs, at least for a transition period, would have removed stress and eliminated the need for every developer to make/import and test a translation map for themselves. A simple developer note, just a few sentences, explaining why there are a different number of mounts and why there’s a new ID would also have been much appreciated and saved me probably a couple hours per sentence.

My experience with pets and titles are similar.

I am thankful the ID spaces for achievements and items seem not to have changed, although the rules for which achievements are shown on which characters seem to have changed (or be busted), and timestamps are sometimes rounded to the nearest minute and sometimes not (which wouldn’t matter except it means my logging meant to expose my own bugs kept alerting me to unexpected changes, requiring more time to investigate.)

Again, you could point to any of these or similar issues and say the API consumer has/had a path to figure it out and fix it, but all adds up to needless time wasted multiplied by however many developers there are that could have been easily saved with brief explanations.

Anyway, thanks for listening, and let me close with some positives. The documentation for wow character status includes a brief blurb explaining why it is there and how you want us to use it. That’s a great example of simple documentation that goes a long way. Mechanically, I’ve found the new APIs to be fast and responsive, and I don’t think I’ve had a single non-200 response yet that wasn’t my own fault. I continue to be impressed with the straightforward, personal and helpful interactions on these forums, so thank you again and happy thanksgiving :wink:

2 Likes
7

Thank you for the response, Ralangee.

I was hoping you might be able to give at least one response. Is Blizzard trying to prevent 3rd party apps from detecting a player’s alts, by removing (or otherwise obscuring) account-wide achievements and timestamps?

I think this question cuts to the heart of several high-priority bugs that I have reported.

If the answer is no, then I am more than happy to just wait for the bugs I reported to be fixed. I can simply inform my users of these bugs.

But if the answer is yes, Blizzard is indeed trying to prevent detection of alts, then this will require a major overhaul to how my site works. To the extent that I might decide to just shut my site down. I feel a leaderboards site is useless if all the rankings are just cluttered with repeats of player’s alts, not to mention that I don’t really feel comfortable exposing a list of alts to the public like that.

Thank you again for your time and I hope you have a great Thanksgiving weekend.

1 Like
8

Just adding my thanks for your response, Ralangee. I appreciate it’s an awful lot of work and it seems like there’s still quite a bit to go, with a looming deadline. Personally, my needs are simple: as long as the new mounts collection Profile API works fully (granted, it isn’t just yet) then I should have all I need. I’m lucky in that I don’t have the complicated many-API requirements of other developers.

As for the thing about the API Bug forum - you’re right about replying not being a normal thing and I wouldn’t normally expect a personal response to a bug report :slight_smile: The only reason I mentioned it here is because a lot of bug reports placed here on the Discussion forum have received replies, which made it look like reports placed here were more visible to your team.

Thanks, and good luck with your work :slight_smile:

9

To be clear, this is what’s been frustrating players and developers for years and what people mean when they say Blizzard is bad at communication. The fact that you’ve been doing it for years make it look worse, not better. You’re literally telling us to keep shouting into a void to get issues fixed. Are you really oblivious to how this extremely disincentivizes bug reports and fosters frustration in the community?