Paste your REST API definition as strong types

If your a developer that spends any time with web services, you’ll basically probably end up working in one of two camps: REST- or SOAP-based services.  Now with SOAP services you’re likely used to having a WSDL document describing the service, providing type definitions, etc. – something you can use developer tools like Visual Studio to Add Service Reference and get a strongly-typed object model to work with.

If you’ve been doing Silverlight or ASP.NET (or any other technology really) development with mashup services, you probably have been working with REST-based services.  These are services that don’t self-describe themselves in a manner like SOAP with WSDL does.  Often I’ve found that really only the larger REST service providers provide good documentation for their services.  As a consumer of a REST service, you’re at the mercy of the documentation to understand the structure of the requests/responses that you’ll be working with…at times that can be frustrating.  If you are like me, you’ve probably either found someone else’s wrapper to the API or tried to work some other method to avoid spelunking the XML nodes.

If you don’t need to take on the full wrapper that you may have found someone already doing and maybe just need to consume something quick or whatever, enter Paste XML as Types.  Located in the WCF REST Starter Kit Preview 2, this is a Visual Studio new option under the Edit menu.  Let’s take a look at an example.

Twitter sounds like it would be a good example, but honestly they provide so many different formats (JSON, XML, RSS) that I’m not sure you would really want the XML version when RSS is more of a known type and easy to work with.  So let’s look at the Flickr API which is a similarly popular one and has a well-documented REST interface.  Let’s say you wanted to work with the results of their ‘interestingness’ public query which will provide you with a list of photos.  We can see in their documentation that they provide us with a sample response:

   1: <photos page="2" pages="89" perpage="10" total="881">

   2:     <photo id="2636" owner="47058503995@N01" 

   3:         secret="a123456" server="2" title="test_04"

   4:         ispublic="1" isfriend="0" isfamily="0" />

   5:     <photo id="2635" owner="47058503995@N01"

   6:         secret="b123456" server="2" title="test_03"

   7:         ispublic="0" isfriend="1" isfamily="1" />

   8: </photos>

Sweet.  Copy that sample response.  Go into Visual Studio in your project class file (or create a new one), go to the edit menu:

Booyah!  Watch as the magic happens and the XML structure is transformed into strong types for you.

Well, sorta.  Turns out while I think this is a cool feature, it might have some work still to go.  My first assumption was that the documentation on Flickr matched exactly the response (heck, it says sample response).  But it really is only the response body.  There was some missing response header nodes.  You should call the API directly to see a real response.  Second, even with that it looks like I’m getting some weird namespace stuff.

But regardless of that, even taking an XML file and being able to reflect on that to create an object model on paste is pretty cool. 

Try this out – if you see issues leave comments on the WCF REST Starter Kit site so they can see them – you’re welcome to leave them here as well, but I’m not on that team and it’s better to give direct feedback on their project.