KevBurnsJr

For any SOAP web service, you are very likely to find a WSDL which describes the service.

WSDL is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information.

However, WSDL 1.1 is really not designed to describe RESTful web services. WSDL 2.0 includes language for better describing RESTful web services, but is still only a recommendation.

So suppose I wanted to automatically generate a JavaScript api for interacting with an arbitrary RESTful web service. I should be able to find an appropriate WSDL, parse the described resource types along with their properties, relationships and urls, create some internal model of the web service based on the properties of those resources and generate some JavaScript classes for interacting with the web service.

This is a rather simplistic example, but it shows what a partial service description might look like …

<service name="Twitter">
  <base href="http://twitter.com"/>
  <resources>
 
    <resource class="User">
      <base href="/users">
      <properties>
        <property name="id" type="int" />
        <property name="screen_name" type="string" />
      </properties>    
      <relationships>
        <relationship type="HasMany" target="Status">
      </relationships>
      <method name="GET"></method> #get user info
      <method name="POST">         #create new user
        <requires type="property" name="screen_name" />
      </method>
      <method name="DELETE">       #delete user
        <requires type="auth" name="owner" />
      </method>
    </resource>
 
    <resource class="Status">
      #...
    </resource>
 
    #...
 
  </resources>
</service>

After parsing this document in Javascript, I should be able to create a set of JavaScript classes that behaves somewhat like this …

Resource.load('http://twitter.com/service-description.wsdl', 'Twitter')
Resource.model('Twitter', 'User');
 
// GET a user's details
var user = Twitter.User.find('123');
var screen_name = user.screen_name;
 
// GET a user's most recent status update
Resource.model('Twitter', 'Status');
var most_recent_update = user.Status.last();
 
// POST a new status update on a user's behalf
var new_status = user.Status.new();
new_status.status = "Look ma, no library!";
user.Status.post(new_status);

Seems pretty powerful, huh?

But if you go to Twitter’s API documentation, you will not find any such machine-readable service description document. Nor does the markup for the plain-text description of the service contain any semantic markup that could be used to generate such a description document.

So why doesn’t Twitter post a machine-readable description of their web service? Are they just dumb?

Well, probably not.

I did about 2 days of digging around and finally came across the following article which leads to many additional articles on the subject (thanks to Bradley Holt in #REST on irc.freenode.net) …

Debate: Does REST Need a Description Language

… and this very succinct conclusion from Mark Baker

REST, WADL, forest, trees

So if you’re writing (or generating) contract/interface-level code which can’t late-bind to all resources, everywhere, you’re not doing REST [...]

Cut the cord already! RPC is dead. You’re not in Kansas anymore.

So if we’re not in Kansas, then where does that put us?