Original Url: http://forum-en.guildwars2.com/forum/community/api/Why-APIs-return-IDs

Cliff Spradlin.3512:

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!

smiley.1438:

Thanks for that information, very interesting read!

Primal Zed.9714:

Great stuff, Spradlin. Excited to see what additions or updates you guys make to the APIs. Thanks for the hard work and for keeping involved on the forum.

DarkSpirit.7046:

Thanks for sharing that information with us. Admittedly when we were making those suggestions, we probably just asked for what we needed, without realizing that we could have extracted that same information from another, more-authoritative, api.

Thanks for taking the time to explain this to us.

Narax.7605:

What about 2 guild APIs? One for name and tag (like guild_names.json) and one for more information (guild_details.json).

kaspi.7164:

Thank you for this great write-up and clarification, Cliff. After seeing this, I’d encourage you to keep the design as clean as possible. From what I see you have it figured up very well. As to be expected from a big company

Under these circumstances, I have no problem querying multiple API endpoints and caching the data on my side.

You mentioned content servers holding the localized names of objectives etc. I think I speak for the majority of us if I say we’d like to be able to query these data too. We can build our own relation tables on our end, but I guess it’s just a matter of time until you provide a comprehensive API map and fill in the blanks with more endpoints that we can call.

As I mentioned somewhere else, I would very much love to have a “last modified” header in your response if you in any way cache your API responses. It would make it so much easier for us to handle the response (e.g. throw it away if the modif <= our cached time).

The Talcmaster.7391:

Cliff, as always you are a credit to your company. This sort of thing goes a long way towards people having reasonable expectations of what is possible and how long it would take to do it.

Katz.5143:

This is worthy of a sticky or at the very least a link from a current sticky. Thanks for the detailed explanation.