Wednesday, January 23, 2008

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 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


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, 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.


  1. Freaking awesome.

    You mentioned it a while ago, but I can tell you've read "RESTful Web Services" (I'm mostly done with it and am loving it).

    Great work!

  2. The links on your post seem to give "internal server errors". Do the MTSP REST API still exist ? or perhaps this is a temporary outage ?

  3. Yeah, due to the way we deployed it, that URL has been retired. The correct URL is It's undergoing pretty constant change right now, so the docs are fairly useless. However, the fact that we use XHTML makes it pretty easy to "intuit" your way around the API, IMO.

  4. It’s the end of the year, and although I skipped 2007, it is my habit to take a look back here on matters

  5. Is this still up and running? The link;vs.90 doesn't fly. After like 2 minutes you get the runtime error ("custom error settings prevent the details from being viewed...")


    Sean S

  6. Not sure what's up with that - I'll ask someone.

  7. OK, it seems that the labs version of this is no longer the actively maintained one. Use instead.