Tuesday, February 3rd, 2009

Big Improvements Coming Soon to WADL

By Avi Flax

Marc Hadley, the creator of WADL, has started working on a new version, which he recently described in Draft WADL Update.

My favorite enhancement is that method elements can now have multiple response child elements, and the status attribute has moved from the representation element to the response element.

For example, if a POST method might return a 200, 201, 202, 400, or 409, and every response might return a JSON or an XML entity, it would be specified with the current version of WADL like this:

<method name="POST">
	<request>
		<representation mediaType="application/json"/>
		<representation mediaType="application/xml"/>
	</request>
	<response>
		<representation status="200" mediaType="application/json"/>
		<representation status="200" mediaType="application/xml"/>
		<representation status="201" mediaType="application/json">
			<param name="Location" style="header" required="true">
				<doc>The location of the newly-created resource.</doc>
			</param>
		</representation>
		<representation status="201" mediaType="application/xml">
			<param name="Location" style="header" required="true">
				<doc>The location of the newly-created resource.</doc>
			</param>
		</representation>
		<representation status="202" mediaType="application/json">
			<param name="Location" style="header" required="true">
				<doc>The location of the resource which will be created, once the work is complete.</doc>
			</param>
		</representation>
		<representation status="202" mediaType="application/xml">
			<param name="Location" style="header" required="true">
				<doc>The location of the resource which will be created, once the work is complete.</doc>
			</param>
		</representation>
		<fault status="400" mediaType="application/json">
			<doc>Aside from a malformed or representation, Bad Request can be caused by a FNAME which is longer than 300 characters.</doc>
		</fault>
		<fault status="400" mediaType="application/xml">
			<doc>Aside from a malformed or structurally invalid representation, Bad Request can be caused by a FNAME which is longer than 300 characters.</doc>
		</fault>
		<fault status="409" mediaType="application/json">
			<doc>Conflicts can be caused if FNAME and LNAME are identical (case insensitive).</doc>
			<param name="Location" style="header" required="true">
				<doc>The location of the conflicting resource.</doc>
			</param>
		</fault>
		<fault status="409" mediaType="application/xml">
			<doc>Conflicts can be caused if FNAME and LNAME are identical (case insensitive).</doc>
			<param name="Location" style="header" required="true">
				<doc>The location of the conflicting resource.</doc>
			</param>
		</fault>
	</response>
</method>

As you can see, only one response element, and each distinct status code and media type combination needs to be specified using a representation or fault element. This is repetitive, redundant, and confusing.

In the new version, this can be specified much more clearly and succinctly like this:

<method name="POST">
	<request>
		<representation mediaType="application/json"/>
		<representation mediaType="application/xml"/>
	</request>
	<response status="200">
		<representation mediaType="application/json"/>
		<representation mediaType="application/xml"/>
	</response>
	<response status="201">
		<param name="Location" style="header" required="true">
			<doc>The location of the newly-created resource.</doc>
		</param>
		<representation mediaType="application/json"/>
		<representation mediaType="application/xml"/>
	</response>
	<response status="202">
		<param name="Location" style="header" required="true">
			<doc>The location of the resource which will be created, once the work is complete.</doc>
		</param>
		<representation mediaType="application/json"/>
		<representation mediaType="application/xml"/>
	</response>
	<response status="400">
		<doc>Aside from a malformed or structurally invalid representation, Bad Request can be caused by a FNAME which is longer than 300 characters.</doc>
		<representation mediaType="application/json"/>
		<representation mediaType="application/xml"/>
	</response>
	<response status="409">
		<doc>Conflicts can be caused if FNAME and LNAME are identical (case insensitive).</doc>
		<param name="Location" style="header" required="true">
			<doc>The location of the conflicting resource.</doc>
		</param>
		<representation mediaType="application/json"/>
		<representation mediaType="application/xml"/>
	</response>
</method>

Each status code gets its own distinct response element, which can contain the various types of representations that may be provided along with that status code. (We also decided to remove the fault element, and just let the status codes speak for themselves.) Also, the Location header can be specified inside the response instead of the representation. Much better!

Progress!

One Response

  1. 12/29/2009
    Jerome Louvel said:

    Hi Avi,

    You’ll be happy to hear that the latest Restlet 2.0 snapshot have support for the latest WADL changes!

    Cheers,
    Jerome

Leave a Comment