Cleaning up with RESTful SOAP As we reported last week [1], Groove Networks showed me its much-anticipated SOAP API, which will be called Groove Web Services, and it’s a beautiful thing to behold. Credit for the design goes to Peter Drayton, who lectured masterfully [2] on the subject of “RESTful SOAP” in October and then, in November, found himself with a one-way ticket to Seattle as Microsoft’s newly appointed .Net CLR Program Manager. REST, in case you’ve managed to avoid this somewhat arcane debate, stands for Representational State Transfer and refers to the architectural style of the Web as articulated by one of HTTP’s architects, Roy Fielding. In his lecture, Peter neatly distilled the REST principles and cogently related them to SOAP Web services: – Model your system as a set of resources. – Assign logical URIs (uniform resource identifier) to resources. – Define schemas for resource representations. – Enable discoverability of resources. – Provide appropriate resource manipulation operations. Because the Groove Web Services API follows these principles closely, it makes immediate sense to a Web developer like me. The resources modeled by GWS are Groove accounts, identities, shared spaces, tools, and the data items controlled by tools. The modeling is accomplished in XML Schema, which is used to define XML documents that represent the resources — or nouns — of a system. As per the Web’s style, a handful of primitive verbs (Read, Update) operate on these nouns. The system as a whole behaves as a linked web of XML documents; you discover resources by traversing that Web. I’ve said it before: hyperlinks matter [3]. That idea seems to be echoing everywhere now. Mark O’Neill, CTO of Vordel, a provider of Web services security solutions, notes on his Weblog [4] that naming Web services with URIs means “that the way in which the Web Service is referenced as a ‘resource’ in a security policy can match the way in which it is referenced by a Web Service client.” When I interviewed Tim Bray, co-inventor of XML and now CEO of Antarctica Systems, he told me: “This whole notion of addressing everything by URI, and composing applications accordingly, just works.” Here’s an interesting measure of the distance traveled in recent months of the occurrences of the term “Web-friendly”: In the SOAP 1.1 spec: 0 In the SOAP 1.2 primer: 9 As we proceed to put the Web back into Web services, we’ll revisit lessons that we learned, or didn’t, about how to design URI namespaces. Software developer Brent Simmons recently proposed Brent’s Law of CMS (Content Management Systems) URLs: “The more expensive the CMS, the crappier the URLs.” He refers to the inscrutable URIs generated by, for example, Vignette, whose Web site represents its customer list with this URL: https://www.vignette.com/contentmanagement/0,2097,1-1-31-1495,00.html There are, of course, conflicting forces at work here. URIs inhabit two parallel ecosystems: meatspace and cyberspace. We humans want URIs to be short, mnemonic, writeable, speakable. We want to be able to bookmark them and e-mail them to friends and colleagues. Unfortunately, we have to invest a lot of intellectual effort to achieve these goals. It’s hard to think up good names for things. So as resources multiply, we tend to delegate naming to the machines — a chore they happily perform, but not in ways helpful to us. We can benefit enormously from de facto standards that guide the choice of names. Naming conventions for e-mail addresses are a great example. My published address is pretty easily discoverable: jon_udell@infoworld.com. Of course, there are a couple of different standards in play. It’s straightforward to map from one namespace to another, though. If you guessed I am reachable at jon.udell@infoworld.com, you’d be right. I just checked; our IT guys sensibly support that flavor too. Microsoft’s e-mail addresses are discoverable, but less easily. If I were the 4th John S[a-z]+ at the company, it would take you five tries to find me: johns@microsoft.com johnsm@microsoft.com johnsmi@microsoft.com johnsmit@microsoft.com On Web sites there are plenty of de facto standards, but they don’t tend to control namespaces very well. Every corporate Web site has a contacts page, a news page, and an about page. But these pages are not canonically available as /contacts, /news, /about. We obfuscate our namespaces with leading directory paths and trailing extensions (.html, .php). It was always a good idea to clean this stuff up. Namespace design is, in fact, an engineering challenge. Now that we’re entering the era of RESTful Web services, perhaps we’ll see that more clearly. 1. /articles/pl/xml/02/11/04/021104plgroove.xml 2. https://www.razorsoft.net/slides/RESTfulSOAP/RESTfulSOAP_files/frame.htm 3. /articles/pl/xml/02/05/20/020520pllinks.xml 4. https://radio.weblogs.com/0111797/2002/11/03.html#a24 Software Development