Sunday, 13 April 2008

RESTful Service Descriptions

Over several blogs recently I've looked at RESTful approaches to enterprise integration, somewhat critically. Despite my conclusion that REST inside the firewall is almost crippled by the lack of service descriptions, I do in fact believe that solutions are imminent. Moreover, once these solutions exist and are socialized, I believe it will be game changing within the enterprise. The solutions will not come from the REST community, who (mostly) stubbornly refuse to admit there is an issue. The solution will come anyway, so let's look at where it stands.

Let's start with what a service description must accomplish in a resource oriented enterprise setting. Let's suppose that we stick some RESTful services inside the enterprise ecosystem of a typical enterprise. What do we need to actually describe about them. Well, several things:

  • Where the URI "entry points" are. Where do you start? If you have resources representing a customer, where EXACTLY are they. If I want to look up customers, do I start at http://myco.com/customers or at http://myco.com/accounts? If you think this is silly because somebody could just tell you, then I say two things: first, even a small company probably has 2000 different entities of interest. URI's are never supposed to change in a perfect world. In the real world, they change all the time, especially for dev and test environments inside the firewall. On the internet you probably use a search engine, read blogs, or get emailed a link. Google doesn't typically index inside the firewall, so this doesn't help. The other options don't scale.
  • Metadata about parameters OK, so you know where to go to ask for a filtered set of your favorite entity. What parameters can you put into the URL, which are mandatory, what are their datatypes, and what are the allowable values? Once you know the entry point above, you can do a GET request and get back some nice document with links galore to things of interest (as in "hypermedia as the engine of application state"). Great, how do you specify the start date and end date? Do you have to specify the account name? If so, what's the parameter called? Can you specify the maximum record size to return? etc...
  • What media types are used Can I get purchase orders in JSON? XML? as an ATOM feed? Pretty simple question. You can get this via HTTP HEAD and/or by setting the accepts request header. Sounds like we don't need this in the service description, right. Well, you often have to do gap analysis before you have physical access to a service. You need to figure out things like: When they come on line with purchase orders next month, will they support JSON or do we need to submit a change request? If you have their latest service description, you know the answer. If that document changes, you can ask questions about why things where added or removed because you have something tangible to compare to.
  • Which HTTP operations can you access In theory, this is what HTTP OPTIONS should answer. In reality, who knows what the answer to HTTP OPTIONS looks like. It should probably be the relevent service description document. So rather than replacing it, HTTP OPTIONS becomes a way of retrieving it.
  • What validity constraints exist on the media types If you are using XML, what schema, DTD, relax-NG description applies? This is a big open issue. For the same reasons as above telling me to "get one and look" doesn't work. More fundamentally, you cannot infer a global constraint by looking at instances that happen to obey it. This problem has been mentioned by several people: stu, Stefan Tilkov, James Strachan, and Dan Diephouse

The spec that seems to be able to deliver on all this without adding a bunch of extra useless weight seems to be WADL. Here's a nice quick example of WADL as used in Jersey (the JSR-311 reference implementation) to give you a sense of it. It's difficult to see how anyone could object to this: it's simple, lightweight, does the above and little else, and is comprehensible. Your eyes will not melt if you try to read it or its spec. Jersey returns the WADL doc when you do an HTTP OPTIONS on the resource. That's sweet! I'm really hoping this gets more attention. I note WADL is coming out of the Java community, not the REST community.

Another exciting development is to clothe your RESTful web services in the Atom Publishing Protocol (AtomPub). AtomPub is a RESTful application protocol for CRUD operatoins on resources that produce Atom Feeds. To see the power, look at how ActiveMQ is proposing to implement a RESTful Queue. This is a nontrivial problem. If you don't see why, follow the link to the discussion at rest-discuss and read the thread.

The use of AtomPub and Atom directly for publishing to web services (as opposed to the typical use case of HTML based blogs) is an idea that's been getting a lot more attention lately. Unfortunately, as James Strachan points out, it doesn't let you easily associate an XML schema when you use the application+xml media type. But it could, with a minor modification. Maybe this problem should be solved at the HTTP level, by introducing the URI to appropriate metadata (such as the XML schema) as a media type parameter. Either way, it's possible that we'll see an application protocol (like AtomPub) wrapping up RESTful web services and filling the gaps within it's constructs.

Finally, there's WSDL 2.0. which will also support REST. At the moment WADL's simplicity and implementation lead seem to make it more interesting to me, but WSDL 2.0 will have to be supported by all the next gen SOAP stacks, so we're likely to see these going dual architectural style and supporting REST too.

Technorati Tags:

Posted by spout at 2:48 AM in the internet, web, web 2.0 and beyond
Responses (1)
« April »
SunMonTueWedThuFriSat
  12345
6789101112
13141516171819
20212223242526
27282930