An online buddy of mine drew my attention to Blizzard’s new Community API for World of Warcraft. For those of you who aren’t familiar with World of Warcraft, it is a massive multi-player online role playing game. They have millions of players. The game is so successful and generates so much cash that Blizzard pays out a dividend to stock holders. Not only do they have millions of players, there’s also a very large community around WoW. The game itself has its own scripting language which you can use to write add-ons. This add-on community is huge with thousand upon thousands of apps written.
There’s also a large variety of third-party sites that provide character and guild management, quest information, gear info, damage simulators, and gear optimization. These types of tools need to access Blizzard’s databases. This is where Blizzard’s new REST-based Community API comes. Originally, a lot of these sites did screen scraping on WoW’s main website to grab information and access character management. Since April, they’ve been developing and publishing a full read and write RESTful interface for their applications. Its seems they picked REST because of the ease of integration between many languages.
Things to note
In browsing the API documentation here’s a few things that jumped out at me
Document by example
The first thing to note is that the API is documented by example. Here’s the URL pattern you use. This is what the HTTP request looks like. This is the JSON data you should send, and this is what the JSON data looks like. IMO, this is what REST API documentation should look like. No WADL. No schema. Just plain, here’s what you can send, here’s what the request looks like. This is the approach I’ve taken with my API documentation. You gotta remember, the people that are going to be integrating with these APIs don’t come from SOAP-land, WS-*-land, CORBA-land, enterprise programming land. All will understand HTTP and JSON pretty easily. This is what I love about REST: “lightweight” interoperability with a very low barrier to entry.
Signature-based Authentication
Hackers are ruthless when it comes to World of Warcraft. I myself was hacked once and had to get my account restored. Blizzard is very careful about this as it creates a lot of support headaches for them. You can use a soft-token via your smart-phone. Or order and get an RSA-like physical token generator when you log into your game. As for the REST api, you need to acquire a public and private key. Authentication is done by hashing your private key along with the current time, URL, and HTTP method.
UrlPath = <HTTP-Request-URI, from the port to the query string>
StringToSign = HTTP-Verb + "\n" +
Date + "\n" +
UrlPath + "\n";
Signature = Base64( HMAC-SHA1( UTF-8-Encoding-Of( PrivateKey, StringToSign ) ) );
Header = "Authorization: BNET" + " " + PublicKey + ":" + Signature;
Amazon does something very similar for many of it’s public REST apis. While not true a true digital signature (sigs are encrypted hashes and don’t include the private key), its very close, and a lot simpler to use and understand for users.
Not very link driven
Can you imagine this API being explained via a set of link publishings rather than a set of URI patterns? I’ve taken advantage of HATEOAS, especially within the HornetQ REST API, but in many cases, just publishing the URI scheme can be very useful. Maybe its data-publishing vs. interaction? With a data-publishing app (WoW) it makes more sense to publish a URI scheme for your REST interface. With an interactive application (i.e. HornetQ REST), HATEOAS, link-driven interfaces make a lot more sense and give you a lot more flexibility.
Versioning?
On one of the forum posts, the developer talked about how he/she planned to version the API in the future. It seems that they will version using URIs. The latest and greatest will always use the same top-level URI schemes. If you want to tie yourself to an older version of the API, the URI scheme will be predicated ith a version identifier:
New API: /api/wow/realms Old API /api/wow/v1/realm/status"
All and all it will be great to see this API evolve over time. This will be a great public display of a REST API and it will be very interesting to see how Blizzard tackles various issues. There’s a lot we can learn here.
Bill the Plumber 