REST and Dream

The REST model embraced by MindTouch Dream is based on patterns.  Each Dream service exposes one or more resources that can be accessed through URIs and can be manipulated via HTTP verbs.  Dream narrows the degrees of freedom that a generic resource would have by only allowing three resource representations: structured XML documents, plain text, and binary streams.  Of the three, structured XML documents is the preferred representation.

Dream also incorporates support for two standards that have emerged since REST was conceived.

• The first is JSON or JavaScript Object Notation.  JSON is an encoding of XML documents as JavaScript expressions.  The advantage of this representation is significant when the requesting agent runs natively in JavaScript, such as a web-browser.
• The second standard is XPath, which is a simple, yet powerful selection language for XML documents.  Built-in support for XPath allows Dream services to only return a subset of the requested data, because the selection is performed server-side rather than client-side.

For example, the following GET operation retrieves the blueprint (i.e. declaration) of the EightBallService:

GET http://myserver/host/blueprints/MindTouch.Dream.Tutorial.EightBallService

This operation will return the following XML document:

<blueprint>
	<assembly>dream.tutorial.8ball, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null</assembly>
	<type>MindTouch.Dream.Tutorial.EightBallService</type>
	<name>Dream Tutorial 8-Ball</name>
	<copyright>Copyright (c) MindTouch, Inc. 2006</copyright>
	<info>http://doc.opengarden.org/Dream_SDK/Tutorials/8-Ball</info>
	<feature>
		<pattern>GET:answer</pattern>
		<description>Returns a random 8-ball message</description>
		<info>http://doc.opengarden.org/Dream_SDK/Tutorials/8-Ball</info>
		<method>GetAnswer</method>
	</feature>
	<feature>
		<pattern>DELETE:</pattern>
		<description>Stop service</description>
		<info>http://www.mindtouch.com</info>
		<method>DeleteService</method>
	</feature>
</blueprint>

To obtain the output in JSON, simply add the dream.out.format=jsonp query parameter to the URI:

http://myserver/host/blueprints/MindTouch.Dream.Tutorial.EightBallService?dream.out.format=jsonp

This results in the following response:

({
	"assembly" : "dream.tutorial.8ball, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null", 
	"copyright" : "Copyright (c) MindTouch, Inc. 2006", 
	"feature" : [ 
		{ 
			"description" : "Returns a random 8-ball message", 
			"info" : "http://doc.opengarden.org/Dream_SDK/Tutorials/8-Ball", 
			"method" : "GetAnswer", 
			"pattern" : "GET:answer" 
		}, { 
			"description" : "Stop service", 
			"info" : "http://www.mindtouch.com", 
			"method" : "DeleteService", 
			"pattern" : "DELETE:" 
		} 
	], 
	"info" : "http://doc.opengarden.org/Dream_SDK/Tutorials/8-Ball", 
	"name" : "Dream Tutorial 8-Ball", 
	"type" : "MindTouch.Dream.Tutorial.EightBallService" 
})

By using the dream.out.select=xpath query parameter we can limit the response to a subset of the document.  This is particularly useful for resources that do not expose their inner structure as nested resources.

http://myserver/host/blueprints/MindTouch.Dream.Tutorial.EightBallService?dream.out.select=feature[path='answer']/method

This results in the following response:

<method>GetAnswer</method>

MindTouch Dream provides several generic processing parameters that augment the native functionality of Dream features, making it easy to integrate with Dream services from various environments.

Additional Reading

• REST for the Rest of Us
• JSON Encoding
• PHP Encoding
• What is SODA?