Wednesday, April 30, 2008

MSDN Updates

Yesterday was a big day for me with respect to MSDN. There were a pair of "the new replaces the old" moments.

 

The first event was the one Larry Jordan amusingly subtitles "There will be only one!" What happened was, the old MSDN finally got turned off - the MTPS-based version of MSDN is now the only version running. http://msdn2.microsoft.com now redirects to http://msdn.microsoft.com. That means no more fun URLs like https://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/programmersguide/shell_basics/shell_basics_extending/fileassociations/fileassoc.asp. Now it's http://msdn2.microsoft.com/en-us/library/bb776847.aspx. Ahh - that's better.

 

Since I helped write the Microsoft/TechNet Publishing System (MTPS), which sits behind the new, one-and-only MSDN website (and the TechNet and Expression websites, for that matter), it was sort of cool to see it "take over".

 

The other thing we did yesterday was to update the MTPS REST API. It's still very much a prototype (i.e. things are broken) but we wanted to push a version out there that has some of our latest thinking in it. Most notably, this release sketches out what we think we want to do for writes. That's right - we intend to support community-authored changes to MSDN (the website supports that now in the form of tags and wiki-like annotations, in case you didn't know).

 

Although I should point out that the writes aren't implemented yet in the REST API because we haven't fleshed out the story for authentication.  But you can see the idea. For example, to add a new tag to an item you'll be able to PUT to http://labs.msdn.microsoft.com/restapi/content/b8a5e1s5/en-us;vs.90/tags/add-tag. And to delete a the foo tag added by user candera you'd DELETE http://labs.msdn.microsoft.com/restapi/content/b8a5e1s5/en-us;vs.90/tags/foo/users/candera. For convenience, we're also planning to support POST to those endpoints with a hidden form parameter of _method, which is set to PUT or DELETE as appropriate. It's just too convenient to be able to drive the service from a browser during development not to do that.

 

Another big change is what lives at ~/content. In this release it's a link to the ~/sites part of the API. In MTPS parlance, a "site" is the host part of a URL (e.g. the "msdn" in http://msdn.microsoft.com). Underneath those are "iroots", which is a lot like a vdir (e.g. the "academic" in http://msdn.microsoft.com/academic). The reason ~/content links to ~/sites is that via ~/sites you can find your way into the TOC tree of any of the content in MTPS…or at least you could if it were hooked up properly everywhere. Still, you can see the idea.

 

That said, we've decided that the link to ~/sites is ugly and we hate it. :) So we'll have to figure something else out there. Maybe a set of virtual TOC nodes that unifies all the TOCs - one node to bring them all and in the API bind them. Or something - we're still noodling on that one.

 

Other changes: we've added ETags and Expires headers to all resources (currently everything is hardcoded to expire 24 hours in the future), fixed some of the encoding problems, added an XHTML DTD where appropriate, and of course there are the obligatory bunch of minor bugfixes. We've also done some slight reorganization of the URLs to fit our evolving understanding of the model, but most things have remained unchanged. I'm curious to hear if anyone has played with the service at all - if you have any questions or feedback, do feel free to contact me.

8 comments:

  1. Your use of PUT to .../tags/add-tags is broken. PUT should be idempotent and represent a modification of the resource at the target URI. It should be either a PUT to .../tags/{tag-name} or POST to .../tags/add-tags or even better .../tags

    ReplyDelete
  2. You're right, of course. Although the operation is idempotent, I hadn't been aware that using 201 with a Location is a no-no. It makes sense, of course - thanks for educating a relative REST newbie!



    I also like the idea of using /tags as the add endpoint, although I need to think through whether there are any issues with that.



    /tags/{tag-name} isn't an option because I'm not sure that the tag the user chooses is going to be the ID we wind up using the the URL. Happens to be now, of course.



    Anyway, thanks again: feedback like this is exactly what I was hoping for.

    ReplyDelete
  3. It'd be nice if the site worked any more.



    Since the change, passport breaks the msdn urls containing brackets when logging on so you get content not found, operation aborted comes up a lot, and it generally doesn't work as well.

    ReplyDelete
  4. Thanks - I'll pass that along.

    ReplyDelete
  5. The team is aware of the problem and is working on putting a fix in place in the coming weeks. Thanks!

    ReplyDelete
  6. 99.999% of the time, I will get a "content not found" the first time I click on any msdn link. This happens both at work and at home (ie 7.0.5730.11):



    Click on this:

    http://msdn2.microsoft.com/en-us/library/ms235291(vs.80).aspx



    Browser gets to:

    http://msdn.microsoft.com/en-us/library/ms123402.aspx?missingurl=%2fen-us%2flibrary%2fms235291%24vs.80%24.aspx



    Clicking again on the same link gets to:

    http://msdn.microsoft.com/en-us/library/ms235291(vs.80).aspx

    ReplyDelete
  7. I'll forward your comments to the team, but I don't observe the same problem when I try it.

    ReplyDelete
  8. Any chance you can capture a trace of the behavior you describe?

    ReplyDelete