Posts about Dream on rest-discuss group

[stephensong]

Hi all,

The only reason I ever even heard of Dream, was because I lurk the rest-discuss group on Yahoo, and Roy Fielding himself posted the following a couple of weeks ago:

"Has anyone looked at Dream yet to see how RESTful it actually is?"

Thus far there have only been two responses - one from Berend de Boer saying it was pretty good, but still used cookies, and that he'd prefer a more declarative approach.

The second response was from Mike Schinkel, and reads as follows:

"Below is their hypermedia file. It shows verb-based methods for services and multiple GETs to the same resource for different methods. Sounds like
POX to me."

with the following being the first section of the "hypermedia file" he included:

<!-- INCLUSION BEGINS --------

<?xml version="1.0"?>
<blueprint>
<assembly>dream.tutorial.8ball, Version=1.0.0.0, Culture=neutral,
PublicKeyToken=null</assembly>
<type>MindTouch.Dream.Tutorial.EightBallServ ice</type>
<name>Dream Tutorial 8-Ball</name>
<copyright>Copyright (c) MindTouch, Inc. 2006</copyright>
<info>http://doc.opengarden.org/Dream_SDK/...l</info>
<feature>
<path>answer</path>
<signature>/</signature>
<verb>GET</verb>
<description>Returns a random 8-ball message</description>

<info>http://doc.opengarden.org/Dream_SDK/...l</info>
<method>GetAnswer</method>
</feature>
<feature>
<path>@inspect</path>
<signature>/</signature>
<verb>GET</verb>
<description>Retrieve service description</description>
<info>http://www.mindtouch.com</info>
<method>GetServiceInfo</method>
</feature>
<feature>
<path/>
<

----- INCLUSION ENDS --->

So, I have two questions:

1. Where did Mike yank this "hypermedia file" from? It includes information that I understood to be specified via a C# attribute on the method. I am interested in using a file such as the above because I would like to use Dream from IronPython, but IronPython does not (yet) support C# attributes.

2. Is Mike's assertion factually correct? It doesn't seem so to me, but I'm not confident enough of my grasp of REST concepts to be sure - and certainly not to attempt a rebuttal.

3. If the answer to #2 is no, will somebody more confident of their REST zen than I post a corrective reply on the rest-discuss group? Otherwise, if you post a suitable reply here, I will undertake to post it (with cowardly attribution of course) back to rest-discuss.

Three question, I have three questions ..... nobody expects the Dream inquisition ... <g>

cheers,

gary

[stephensong]

Is somebody able to please resurrect the XML I actually posted?

gary

[SteveB]

I'm currently traveling, so I will keep this short and post a more in-depth reply later.

The XML fragment above is a service blueprint. It describes how methods of a .Net class can be mapped to URIs and verbs. The blueprint is required to register a class with the Dream host. It can either be provided explicitly or generated via reflection with the use of attributes. To get a list of all registered blueprints in your Dream environment go to http://localhost:8081/host/blueprints.

Dream is flexible enough to implement both pure RESTful services as well as hybrid ones. In almost all Dream tutorials, we respond with XML documents, but that's just our implementation choice. Also, the Dream framework provides automatic conversion from XML to JSON/PHP/Microformats/etc. making it very convenient for consuming structured data in different situations.


Cheers,

- Steve

[SteveB]

done

[stephensong]

Thanks for your reply, Steve (and for cleaning up my borked XML).

Is there a straightforward way of specifying the feature information (verb, path, signature, info) without the use of C# attributes? If so, then it should also be possible to utilise Dream from IronPython, which I would very much like to do.

On the RESTful thing, Mike's objection seemed to me to be that Dream implemented a SOAPish/RPC style of hiding the verbs inside message payloads, and piping them all through a single URI endpoint. Either he has misunderstood how Dream works, or I've misunderstood the basis of his criticism. Either way, engaging in some constructive dialog on the rest-discuss group might be an effective way of promoting Dream to a very knowledgable and discriminating audience - yes? It might also assist noobs such a myself in getting up to speed with Dream.

thanks,

gary

[SteveB]

Yes, it is possible to register a service without attributes. It follows a similar procedure like registering a service with attributes.

Normally, you only need to register the assembly and class names as such:
<blueprint>
<assembly>assembly_name</assembly>
<class>Namespace.ClassName</class>
</blueprint>

The framework will then extract the remaining information automatically.

However, you can also provide this information manually and thus forgo the need to use attributes. Below is a complete blueprint post as generated by using attributes.
<blueprint>
<assembly>mindtouch.core</assembly>
<class>MindTouch.Dream.Services.HostService& lt;/class>
<name>MindTouchDreamHost</name>
<copyright>Copyright(c)2006MindTouch,Inc.&lt ;/copyright>
<info>http://doc.opengarden.org/Dream_API/...t</info>
<sid>http://www.mindtouch.com/services/20...st</sid>
<feature>
<signature>services/</signature>
<verb>GET</verb>
<description>Retrievelistofallrunningservice s.</description>
<info>http://doc.opengarden.org/Dream_API/...t</info>
<method>GetAllServices</method>
<acceptstatus>200</acceptstatus>
</feature>
<feature>
<signature>blueprints/</signature>
<verb>GET</verb>
<description>Retrievelistofallblueprints& lt;/description>
<info>http://doc.opengarden.org/Dream_API/...t</info>
<method>GetAllBlueprints</method>
<acceptstatus>200</acceptstatus>
</feature>
<feature>
<signature>blueprints/*</signature>
<verb>GET</verb>
<description>Retrieveablueprint</description>
<info>http://doc.opengarden.org/Dream_API/...t</info>
<method>GetBlueprint</method>
<acceptstatus>200</acceptstatus>
</feature>
<feature>
<signature>register/</signature>
<verb>POST</verb>
<description>Registeraserviceblueprint.&l t;/description>
<info>http://doc.opengarden.org/Dream_API/...t</info>
<method>RegisterServiceType</method>
<acceptstatus>200</acceptstatus>
</feature>
<feature>
<signature>load/</signature>
<verb>POST</verb>
<description>Loadanassemblyandregisterallcon tainedservices.</description>
<info>http://doc.opengarden.org/Dream_API/...t</info>
<method>LoadAseembly</method>
<param>
<name>name</name>
<valuetype>string</valuetype>
<description>Nameofassemblytoload</description>
</param>
<acceptstatus>200</acceptstatus>
</feature>
<feature>
<signature>unregister/</signature>
<verb>POST</verb>
<description>Removeaserviceblueprint.</description>
<info>http://doc.opengarden.org/Dream_API/...t</info>
<method>UnregisterServiceType</method>
<acceptstatus>200</acceptstatus>
</feature>
<feature>
<signature>start/</signature>
<verb>POST</verb>
<description>Startaserviceinstance.</description>
<info>http://doc.opengarden.org/Dream_API/...t</info>
<method>PostStartService</method>
<acceptstatus>200</acceptstatus>
</feature>
<feature>
<signature>stop/</signature>
<verb>POST</verb>
<description>Stopaserviceinstance</description>
<info>http://doc.opengarden.org/Dream_API/...t</info>
<method>PostStopService</method>
<acceptstatus>200</acceptstatus>
</feature>
<feature>
<signature>shutdown/</signature>
<verb>POST</verb>
<description>Shutdownhostserviceandallrunnin gservices</description>
<info>http://doc.opengarden.org/Dream_API/...t</info>
<method>PostShutdown</method>
<acceptstatus>200</acceptstatus>
</feature>
<feature>
<signature>execute/</signature>
<verb>POST</verb>
<description>ExecuteanXMLscript</description>
<info>http://doc.opengarden.org/Dream_API/...t</info>
<method>ExecuteScript</method>
<acceptstatus>200</acceptstatus>
</feature>
<feature>
<signature>test/</signature>
<verb>*</verb>
<description>TestcommunicationwithHostservic e</description>
<info>http://doc.opengarden.org/Dream_API/...t</info>
<method>CommunicationTest</method>
<param>
<name>status</name>
<valuetype>int</valuetype>
<description>Responsestatuscodetoreplywith(d efault=200)</description>
</param>
<acceptstatus>200</acceptstatus>
</feature>
<feature>
<signature>xmltransform/</signature>
<verb>POST</verb>
<description>ApplyaXML-transform(xslt)toadocument</description>
<info>http://doc.opengarden.org/Dream_API/...t</info>
<method>XmlTransform</method>
<param>
<name>xslt</name>
<valuetype>uri</valuetype>
<description>SourcelocationofXSLTdocument&lt ;/description>
</param>
<acceptstatus>200</acceptstatus>
</feature>
<feature>
<signature>convert/</signature>
<verb>POST</verb>
<description>Convertadocumenttoanotherformat </description>
<info>http://doc.opengarden.org/Dream_API/...t</info>
<method>XmlConvert</method>
<acceptstatus>200</acceptstatus>
</feature>
<feature>
<signature>@config/</signature>
<verb>GET</verb>
<description>Retrieveserviceconfiguration&lt ;/description>
<info>http://doc.opengarden.org/Dream_API/...s</info>
<method>GetConfiguration</method>
<acceptstatus>200</acceptstatus>
</feature>
<feature>
<signature>@inspect/</signature>
<verb>GET</verb>
<description>Retrieveservicedescription&l t;/description>
<info>http://doc.opengarden.org/Dream_API/...s</info>
<method>GetServiceInfo</method>
<acceptstatus>200</acceptstatus>
</feature>
<feature>
<signature>/</signature>
<verb>DELETE</verb>
<description>Stopservice</description>
<info>http://doc.opengarden.org/Dream_API/...s</info>
<method>DeleteService</method>
<acceptstatus>200</acceptstatus>
</feature>
</blueprint>

Once you have the blueprint ready, POST it to:
http://localhost:8081/host/register

I haven't had time to try this out yet, but the code path is the same for both registration methods so it should work. Let me know how it goes.

Also, the above blueprint is for 'Crimson' which isn't released yet, but is available from our nightly build SVN tree.


Cheers,

- Steve

[stephensong]

Hi Steve,

Thanks again for your response. It took me a few goes, but I've now got it working. By studying the code, I eventually figured it out that it is an "all or nothing" thing, based on the presence/absence of the name element on the service. So now, on to IronPython (he says, tragically optimistic as always ;-).

I notice the feature elements listed in your post contain no "path" element. Is this a change in Crimson? How does it work? I mean, how/where is the path (or equivalent) specified?

I am reluctant to install Crimson without some documentation as to the changes/gotchas introduced. Is such info easily obtainable from the svn?

cheers,

gary

[SteveB]

In Crimson, we decided to combine the path and signature elements into a single signature element. However, we made it so that it remains backwards compatible. So, if you use path + signature, it will continue to work in Crimson as well.

I keep a fairly detailed log of changes if you're curious to see what's changing in Crimson.

Cheers,

- Steve