Silverlight: REST API Microformat

So my question is how about a Microformat for when describing REST API's?

I've been wanting to create lots of cool little Silverlight applications against all the various cool api's that have sprung up over the years (and more frequently recently).  An example list is below.

• Blogger
• You Tube
• MTV
• Twitter
• and many many more

All of these API's are REST / Simple HTTP based protocols, not SOAP.

Very quickly, I have got annoyed with the API's as it's been to much of a pain, trying to get a decent client library to work with the API's.  All have different flavors, support different features, not supported any more, lots of assemblies and integration, a real pain.

Even if you do find a decent client library, it might not work with Silverlight and even if it does, you end up with API assembly bloat.

Client Proxies

The big issue as far as I can see it is that decent client proxy generators don't seem to exist.  You either have to download a client library built by the developer / an open source project / build one yourself.

This issue is being tackled in many places trying to simplify the issue

• WCF REST Starter Kit
• DSL's (OSLO)
• C# 4.0 (dynamic)

From my point of view, I really want to just fire visual studio at a url, let it generate me a proxy, and then start working with it.

SOAP Proxies

One of the real advantages of SOAP based web services is that you can do just that, you point Visual Studio at the service and it will generate a nice little proxy with some lovely intellisense and you can work with the service very quickly.

This is great for enterprise / internal projects, not so great for Internet based projects, as REST is generally the chosen way forward.

The reason it's easy to generate a proxy with SOAP is that SOAP based Web Services have a WSDL document that describes the service interface.

WADL

So in the Java world, they are trying to push a similar concept to WSDL which is WADL.  The WADL document will describe your service interface (just like WSDL).  I don't personally like WADL and I don't think it will catch on, it doesn't really fit well with REST (in my opinion).  This hasn't seemed to have taken off in the .NET world, and I don't expect it to either.

Microformats

So why do I think there should be a Microformat for REST / simple http based API's.  Well pretty much of these API companies seem to write lots of html based documentation on  how to use their lovely new api.  Pretty much of all of these companies have pretty much the same sort of descriptions / formats.

Therefore it isn't too much of a pain to use a Microformat within the html.  This would allow me to point Visual Studio straight at the documentation, and have it generate me a proxy, bizarre I know.

This would also allow all the existing api's to support it, with very  little effort, not get in the way of any other service definition standardization etc, etc.

It would also be platform / language agnostic.

I know it seems a little crazy but how long would it take these companies to mark up their existing documents with the Microformat (not very long), you could then use whatever mechanism in your toolset to autogenerate docs.

So this is my crazy idea for the day, feel free to slate it.

The following is a sample address microformat

<div class="adr">
 <div class="street-address">665 3rd St.</div>
 <div class="extended-address">Suite 207</div>
 <span class="locality">San Francisco</span>,
 <span class="region">CA</span>
 <span class="postal-code">94107</span>
 <div class="country-name">U.S.A.</div>
</div>

Tha type of format could be easily modified to suit description of services, which ultimately would mean that a human could read it, and Visual Studio could generate a proxy from it.

Query parameters could be marked up with their type, their description.  Base Uri's could be marked up.

Anways, let the slating begin :)

If it seems a reasonable suggestion however, then I think its something that could be done quickly and could work with todays toolsets.