Announcing the MTPS REST API

If you've been reading my blog for long, you know that a while back I wrote the MTPS Content Service. And you've probably also noticed that as part of that experience, I learned a lot about SOAP and REST. Well, those lessons weren't just academic; for the last few months I've been working on the next generation of MTPS web services, and this time, they're RESTian!

 

As of today, you can go out to http://lab.msdn.microsoft.com/restapistubs/ and see for yourself. That URL is the root of a prototype REST API that exposes basically everything that the SOAP API does, plus a bunch of other pieces of information. Over the coming months, we'll be adding more functionality to it, too, as we try out some of our ideas for MTPS web services V.next.

 

Before going any further, I'd like to stress that this service is a prototype. You've probably noticed the "lab" part of the domain name in the URL. Well, we're serious: we will be updating and modifying the service over the coming weeks. Don't count on piece of data to stay in the same place, to stay in the same format, or even to work at any given time. That said, we expect a trajectory towards increasing functionality and stability.

 

There are a few notable things about the new service. Aside from the obvious fact that it's REST, not SOAP, perhaps the most significant thing is that the data format is fundamentally different. Specifically, 99% of the returned data is XHTML rather than the XML custom grammars that the SOAP service returns. Do a "view source" on something like the page for System.Xml.XmlReader, and you'll see what I mean. Basically, instead of using custom elements like <locale> or <version>, we've gone with things like <span class="locale"> and <div id="version"> instead.

 

This approach has two major benefits. The first is that you can use the service from a web browser. It won't look pretty  - the format is designed primarily to carry structured data, and only secondarily to be viewable - but you won't need to write any client software to get a pretty good idea of how the service is set up. My experience writing the service is that this is actually a really useful attribute.

 

The other benefit of this approach is that it's, well, XHTML. That is, there are certain things about the grammar that are already understood by any person or automated tool that knows XHTML. So if you see <a href="some/url"> in the data, you know right there that the item you're looking at and the one linked to have a relationship. Not only that, but you know how to retrieve it. You could achieve the same thing with a custom XML grammar, but a) why reinvent the wheel, and b) you'd probably never be able to teach existing web tools (think search engines) what your custom grammar meant.

 

On the downside, XHTML is currently a little harder to work with from a client standpoint than an XML grammar designed to deserialize to an object graph. In my opinion, that has changed somewhat with .NET 3.5, and specifically System.Xml.Linq. I've written a bit about that already here and here and may have a bit more to say about it in a future post.

 

I'd like to call out two features that are unique to the new version of the service: tag and annotation info. If you visit http://lab.msdn.microsoft.com/restapistubs/community, you'll see links to these two sections of the website. This is data reflects a feature that's been on the MSDN website for quite some time, but that seemingly not a lot of people know about - you can tag and/or annotate items in the documentation with your own tags and comments. Check out this as one example of community-added content.

 

Right now, the tag and annotation data available through the REST API is "fake". That is, it's just a bunch of placeholder information, and doesn't reflect the contents of the MTPS database. That's just because we're still running with the version I developed on my laptop as we iron out the last issues with connecting the service to the live database. But it should be hooked up to the real annotations and tags before long, and you'll hear about it here when it is.

 

OK, I think that's enough info for now. I'll post more before long.