Wednesday, January 23, 2008

Design and Implementation - Episode 2

Tim and I sat down and recorded our second episode of "Design and Implementation", our occasional podcast. In this episode, we discuss the newly-launched MTPS REST API.



If you missed our first episode, get it here.

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.

Thursday, January 10, 2008

Moving On From FlexWiki

It has been something like four years that I’ve been working on FlexWiki. Not very quickly at times, but I do at least try to put in around an hour every day. For quite a while now, that hour has become more a chore than something I look forward to. But I was committed to completing the tasks I said I would take on, so I kept going.


Well, now I’m done. I even checked in my experimental output caching code, although it's not in the 2.0 release.  


All this is by way of saying: I’m leaving the project. It’s in a good place technically, we’ve got some very competent developers still doing great work on the app, and more and more it’s someone besides me answering user emails. I feel absolutely great about the people that remain being able to maintain and improve the product. There are, of course, any number of things that I’d love to fix or add to FlexWiki, but the truth is that I’m just burned out. Plus, our second child is due to arrive in a few weeks, and I think it would be foolish to assume even my limited free time is going to survive that.


So what am I going to do with that hour a day? Not sure yet. Maybe just savor it in the weeks before the birth. :)

FlexWiki 2.0 RTW Available

It's been a little over month since we released FlexWiki 2.0 RC1. Well, unlike certain software companies I could name, when we say "Release Candidate", we mean it: we couldn't find anything majorly wrong with that version, so today I slapped a new label on it and sent it off into the world as FlexWiki 2.0 Released to Web (RTW) version.


So if you've been waiting for FlexWiki to shed its beta and RC monikers, go forth and download it from the project website!


Thanks again to Derek, John, and Nathan for their contributions, as well as to those others who have contributed since the FlexWiki 1.8 days (sadly, I don't have a list handy).


As this concludes something more than two years of work on my part, you can imagine that I'm pretty pleased.