I’m writing this in response to a lot of suggestions posted that have a similar theme.
Some examples:
- “The WvW match detail API should return guild names, not just guild IDs.”
- “The event names API should return map IDs”
- “The recipe API should return item names, not just item IDs”
I totally understand the desire to be able to make just one API call and have it return exactly what you want. I’m going to first explain why it’s not always feasible with the current API implementation, and after that talk about some possible solutions to the problem.
While the API servers seem like a single endpoint from an external developer’s perspective, they actually consist of many backend servers that service different parts of the API. Different information is on different servers.
Lets use the WvW / guild name feature request as an example. There is a WvW server, and a guild server. The WvW server holds all the WvW information, which includes references to guilds (guild IDs). The WvW server does not report any information about guilds, their names, emblems, etc. because it is not authoritative for that information — the guild server is.
At the scale of Guild Wars 2, no single server can hold all the information about the game. Instead, the information is distributed amongst many different servers. In fact, there is not just one guild server, there are many guild servers. And likewise there are many WvW servers. It’s very difficult to keep the same information in-sync between all these different servers reliably, so it’s much easier for the servers to hold references to the information, and then ask the authoritative server for details if details are needed.
So if we wanted to show guild names as part of the WvW match results, the WvW API server has to query the guild server for that information. Then we’d have to decide on a retention policy for that information — theoretically guild names can change. Should we send the query each time a WvW API request comes in, or should we try to cache the information on the WvW API server? Either way, it adds a significant amount of complexity to the WvW API server.
That leads to the next problem, which is deciding which information to include. First, there was a request for guild name and guild tag — but there’s also been a request for guild emblems to be included. So should we include those in the WvW match results too? What if somebody doesn’t want the guild emblems, they only want the guild name or guild ID because they already have downloaded information about the guild before? Should they be forced to waste bandwidth and time processing information they already got before?
By the way, objective names and details have the same problem — the WvW API server only knows about objective IDs, not objective names. The objective names are defined in our game localization files. We have another server that parses the localization files, called the Content server. When you ask for objective names, you’re actually querying the Content servers for that data.
Hopefully you can see the pattern here. The point is it’s much simpler (for us) to write API servers to return just the information they know, and for you to connect the information from the different APIs together. The simpler it is for us to write APIs, the more APIs we can create for you.
As I said before, I completely understand the desire to make a single API call and get everything you want. There are some attempts at solutions to this problem. YQL ( http://developer.yahoo.com/yql/ ) is an example. YQL is a SQL-like query language that can join and filter the results of different web APIs together. So you could write something like this in YQL:
“SELECT objective_id, match_id, guild_name FROM gw2_wvw JOIN gw2_guilds ON (gw2_wvw.guild_id = gw2_guilds.guild_id) WHERE gw2_wvw.world_id = 1001”
Facebook offers similar functionality to their data using a similar system called FQL.
I consider these types of interfaces to be a new layer on top of our existing API servers. They’re nice to have, but their only functional advantage is that they make the APIs easier to use and reduce the number of API calls made.
We’re currently focused on creating new APIs, because new APIs will enable new cool applications. Maybe once we have lots of cool APIs, we can spend some time on these nice API wrapper layers.
I hope this was helpful. Thanks for reading!
