Bill the Plumber

Mark posted a really nice article to InfoQ: WebSockets vs. REST?

From what I understand of Websockets, its bascially used to set up a two-way socket connection and not really an application protocol. What worries me the most is that you’ve basically rolled back 20 years of protocol consolidation, and we’re now back to a free-for-all of everybody’s pet protocol. Not so bad if your client and server are a tightly coupled, unreusable UI application. Really bad if you’re writing a web service that is supposed to be reusable by unknown heterogenous clients. With Web Sockets, web services are not only going to have to negotiate the media type, but also the application protocol. Seems like a huge step backward to me in terms of integration.  Did we forget all the problems we had with Oracle Forms, PowerBuilder, Visual Basic and all the UI/framework specific protocols all those developer frameworks introduced?  Do we really want to go back to those days?

What about security issues?  With an anything-goes socket protocol, isn’t this a security nightmare for our operations folks?

Disclaimer:  You could say that I’m both biased and threated by the concept of Web Sockets given my involvement in REST frameworks and APIs.  But in all honesty, I’d be very happy to embrace a new protocol that is both ubiquitous and easily supportable and interoperable in many different languages and platforms.  There’s much to be said about the simple request/response text-based approach of HTTP (and REST over HTTP).  While it may not be uber-efficient, its just so easy to hack and support.

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.

I’m catching up on some blog reading.  A great blog on REST, if you don’t read it already, is Subbu Allamaraju‘s (in my blog links too).  I like to call him Dr. REST.  Back in May he wrote about Richardson’s Maturity Model and how measuring your APIs against the model is the wrong thing to do (I think he’s followed it up with a presentation).  I can’t agree more.  What I like about this model (and other articles like it) is that I like to compare it to my own history of growing my understanding of REST.  IMO, what you should do these models and guidelines is read them, examine them, see if they spark any ideas for improving your application.  They just might improve your understanding of REST and why certain constraints are good.  Don’t try to fit your API to REST.  Let REST help you write a better API.  Don’t apply REST for the sake of REST.  This is primarily why I unplugged myself from the rest-discuss mailing list.  If you treated applying REST as a set of guidelines instead of a set of laws you were castigated for it.  Wrong approach.

Anyways, as usual, great blog Subbu.  BTW, you should check out his book too.