Well,
I warned you that we'd be updating the MTPS REST API (located at
http://lab.msdn.microsoft.com/restapistubs/). And we did. A bunch of things have changed. Mostly, I've added new functionality. I did, however, change the way one thing works in a fairly significant way, but it just makes for a good opportunity to talk a bit about how the service works.
If you visit
the content section of the service, you'll be given a list of all the content item IDs in the system. (A content item is an atom of information - for example the documentation for one of the overloads of System.Xml.XmlReader.Read.) Right now that list is very short, because we're still not hooked up to the live database, so the bits that I can't get from
the MTPS SOAP service, I just make up. You can tell because they all have "fake" somewhere in the URL. Eventually, we'll list all the content items here. Not because I think that a list of all the content items is inherently useful in and of itself (although you never know), but rather because I believe that every URL in the system ought to be reachable by traversing links from the service root.
Clicking on the only non-fake content item ID takes you
here. This is what we call the alternates list for the content item, which happens to be the System.Xml.XmlReader content item. "Alternates" because it lists all of the available versions/locales pairs. See, every content item can exist in multiple versions and in multiple languages. So you can click
here to get the German, .NET 2.0 version of the System.Xml.XmlReader content item, or you can click
here to get the US English, .NET 3.5 version of the same document.
Once you click one of those links, you arrive at the content item page. (You can always tell what type of page you're on by examining the class of the <body> tag.) Here, you get links to all the various pieces of information that make up the content item. One of the most interesting is the Mtps.Xhtml primary document. This document contains most (but not all) of the information you're used to seeing on
the MSDN2 website when you look up a class or method. And here's where one of the changes came in.
In the first version of the service that I posted, if you were to look at an Mtps.Xhtml document (for example,
this one), you'd find that clicking in the links it contains would jump you to the other Mtps.Xhtml documents. At first blush, this is a fairly natural thing to do, as it mirrors what happens on the MSDN2 website. However, there was a subtle problem lurking that came up, and now the service no longer behaves that way. Now, if one content item links to another in the Mtps.Xhtml document, that link takes you to the list of alternates for the target document.
This has a number of implications. First of all, it means that if you want to use the MTPS REST API as a (really ugly) documentation browser, you're going to do a lot more clicking. To navigate from one Mtps.Xhtml document to another, you're going to have to click once to get to the list of alternates, again to pick a particular version/locale combo, and then again to get to the Mtps.Xhtml primary document. Not optimal from a human standpoint it's worth mentioning that the REST API is not designd to be navigated by a human…except developers who want to get an idea of how it works.
No, there's a good reason for this change. You see, it turns out that the underlying MTPS database doesn't actually contain version or locale information. You can see this if you use the SOAP service - that document that comes back is linked solely via something called an asset ID, which is basically like the "b8a5e1s5" (we call that form a "short ID") part of the URL for a content item. In the initial release, I actually wound up just using the locale and version of the linking document to synthesize a link to the target document. Obviously, this would break if the target document happens to be of a different locale and/or version. And it did.
But that's not the reason we changed it. The real reason is that it's not clear that the service should be defining what the correct behavior should be. Should we always send links to the latest version? To the same version? If you think you know the answer for your scenario, let me assure you that someone else will have a different one. On the MSDN2 website, we can make assumptions about which way it should go because it's not an API, it's an application. But the REST interface is an API. So we have to leave it to the client, which means linking to the alternates page, so the client can implement whatever policy they want - pick the latest, pop up a dialog, whatever.
I mention this because to me, it's really characteristic of the RESTian nature of the interface in two ways. First, we leverage links, rather than expecting clients to synthesize URLs based on knowledge of how the system works. It emphasizes the view of the system as a directed graph of linked resources. That has more of the "of the web, not just on the web" flavor that (IMO) characterizes good REST interfaces.
The other thing that it brings home is that the REST API is not a website in the traditional sense. That is, it's not that I've just built a website and decided that all my .aspx pages now have .xml siblings or whatever: the system is fundamentally designed in a different way - to expose as much of the information available in the database as possible, not to present it for human consumption. Which goes part way towards explaining my decision not to include stylesheet links in the head, too. (A post for another day, perhaps.)
So this has turned into a somewhat long (and perhaps somewhat rambling) post about a service that - as far as I know - no one is using yet (tell me if you are). But as the first major REST system that I've implemented "for real", I've found the issues that come up to be enormously helpful towards my understanding of the advantages and limitations of REST. Hopefully some of you will, too.
I hope to occasionally post more information about the design and implementation of the MTPS REST API, and about the things I'm learning from it, as we move forward.
