WADL Overview

Sang Shin
JPassion.com
“Learn with Passion!”

1
Agenda
• What is and Why WADL?
• WADL document structure
• Example mapping between a HTTP request and WADL
• WADL examples
> Yahoo News Search
> Atom Publishing Protocol

2
What is and why
WADL?

3
What is WADL?
• Web Application Description Language
> Machine-friendly site map
> HTTP assumed
• XML-based language
> Not restricted to XML payloads (can handle JSON, etc.)
> Uses hyperlinks for composability
• Development language+platform neutral
• Aligned with REST terminology

4
Why WADL?
• WADL is designed to provide a simple alternative to WSDL for
use with XML/HTTP Web applications.
• To date such applications have been mainly described using a
combination of textual description and XML schema, WADL
aims to provide a machine process-able description of such
applications in a simpler format than is possible using WSDL.
(quoted from Marc Hadley's “Introducing WADL blog -
http://weblogs.java.net/blog/mhadley/archive/2005/05/introducin
g_wad.html)

5
WADL Document
Structure

6
WADL Elements
• Resources
> Identified by a URI
> Specify which HTTP methods are supported
• Methods
> Specify details of request and response contents
> Often refer to representations
• Representations
> Describe the format of a HTTP entity
> Can refer to grammars
• Grammars
> Specify use of W3C XML schema
7
WADL Document Structure
<application>
<doc/>*
<grammars/>?
<resources base='anyURI'>?
<doc/>*
<resource path='template' type='anyURI+'?>+
<doc/>*
<param/>*
( <method/> | <resource/> )+
</resource>
</resources>
( <method/> | <representation/> | <fault/> |
<resource_type/>)*
</application>

8
WADL Method Structure
<method name='NMTOKEN'? id='ID'?
href='anyURI'?>
<doc/>*
<request>?
<param>*
<representation/>*
</request>
<response>?
( <representation/> | <fault/> )*
</response>
</method>

9
WADL Param Structure
<param name='NMTOKEN'
style='query|matrix|template|header'
type='QName'
default='string'
path='string'
required='boolean'
repeating='boolean'
fixed='string'>
<doc/>*
<option/>*
<link resource_type='anyURI'
rel='string' rev='string'/>?
</param>

10
WADL Resource Type Structure
<resource_type id='ID'>
<doc/>*
<param/>*
<method/>*
</resource_type>

11
Example Mapping
between a HTTP
Request and WADL

12
Mapping of Base URL
GET http://bookmarks-online.com/ api/v1/bookmarks?
userId=tom&tags=rest&limit=10

<?xml version="1.0" encoding="utf-8"?>

<application
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xsi:schemaLocation="http://research.sun.com/wadl/2006/10 wadl.xsd"
xmlns="http://research.sun.com/wadl/2006/10"
>
<resources base="http://bookmarks-online.com/ ">
<resource path="api/v1/bookmarks">
<method name="GET">
<request>
<param name="userId" type="xsd:string" style="query" />
<param name="tags" type="xsd:string" style="query" />
<param name="limit" type="xsd:integer" style="query" />
</request>
</method>
</resources>
</application>

13
 Mapping of URL Path
GET http://bookmarks-online.com/api/v1/bookmarks?
userId=tom&tags=rest&limit=10

<?xml version="1.0" encoding="utf-8"?>

<application
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xsi:schemaLocation="http://research.sun.com/wadl/2006/10 wadl.xsd"
xmlns="http://research.sun.com/wadl/2006/10"
>
<resources base="http://bookmarks-online.com/">
<resource path="api/v1/bookmarks">
<method name="GET">
<request>
<param name="userId" type="xsd:string" style="query" />
<param name="tags" type="xsd:string" style="query" />
<param name="limit" type="xsd:integer" style="query" />
</request>
</method>
</resource>
</resources>
</application>

14
Mapping of HTTP Method
GET http://bookmarks-online.com/api/v1/bookmarks?
userId=tom&tags=rest&limit=10

<?xml version="1.0" encoding="utf-8"?>

<application
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xsi:schemaLocation="http://research.sun.com/wadl/2006/10 wadl.xsd"
xmlns="http://research.sun.com/wadl/2006/10"
>
<resources base="http://bookmarks-online.com/">
<resource path="api/v1/bookmarks">
<method name="GET">
<request>
<param name="userId" type="xsd:string" style="query" />
<param name="tags" type="xsd:string" style="query" />
<param name="limit" type="xsd:integer" style="query" />
</request>
</method>
</resources>
</application>

15
Mapping of Parameters
GET http://bookmarks-online.com/api/v1/bookmarks?
userId=tom&tags=rest&limit=10

<?xml version="1.0" encoding="utf-8"?>

<application
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xsi:schemaLocation="http://research.sun.com/wadl/2006/10 wadl.xsd"
xmlns="http://research.sun.com/wadl/2006/10"
>
<resources base="http://bookmarks-online.com/">
<resource path="api/v1/bookmarks">
<method name="GET">
<request>
<param name="userId" type="xsd:string" style="query" />
<param name="tags" type="xsd:string" style="query" />
<param name="limit" type="xsd:integer" style="query" />
</request>
</method>
</resources>
</application>

16
Yahoo News Search

17
Yahoo News Search
• http://developer.yahoo.com/search/news/V1/newsSearc
h.html
• Query parameters
> appid: get this from Yahoo by registering
> query: space separated list of keywords
> many others including language, sort, result count etc.
• Get back results as XML, JSON or PHP
> XML schema available for normal and error responses

18
19
Yahoo News Search WADL (1)
<application xmlns:...>

<grammars>
<include href=".../NewsSearchResponse.xsd"/>
<include href=".../NewsSearchError.xsd"/>
</grammars>

<resources
base="http://api.search.yahoo.com/NewsSearchServ
ice/V1/">
<resource path="newsSearch">
<param name="appid" type="xsd:string"
required="true" style="query"/>
<method href="#search"/>
</resource>
</resources>

20
Yahoo News Search WADL (2)
<method name="GET" id="search">
<request>
<param name="query" type="xsd:string"
required="true" style="query"/>
<param name="type" type="xsd:string"
default="all" style="query">
<option value="all"/>
<option value="any"/>
<option value="phrase"/>
</param>
...
</request>
<response>
<representation href="#resultSet"/>
<fault href="#searchError"/>
</response>
</method>

21
Yahoo News Search WADL (3)
<representation id="resultSet"
mediaType="application/xml"
element="yn:ResultSet">
<doc xml:lang="en"
title="A matching list of news items"/>
</representation>

<fault id="searchError"
status="400"
mediaType="application/xml"
element="ya:Error"/>

22
Atom Publishing
Protocol

23
Atom Publishing Protocol
<service xmlns...>
<workspace>
<atom:title>Main Site</atom:title>
<collection href="http://..." >
<atom:title>My Blog Entries</atom:title>
<accept>entry</accept>
<categories href="http://..." />
</collection>
<collection href="http://..." >
<atom:title>Pictures</atom:title>
<accept>image/*</accept>
</collection>
</workspace>
</service>

24
App Service Doc using WADL
<application xmlns...>
<resources base="http://example.org/">
<resource path="reilly/main"
type="http://.../app.wadl#feed"/>
<resource path="reilly/pic"
type="http://.../app.wadl#media"/>
</resources>
</application>

25
App Feed Resource Types
<resource_type id="feed">
<method href="#getFeed"/>
<method href="#addEntryCollectionMember"/>
</resource>

<resource_type id="media">
<method href="#getFeed"/>
<method href="#addEntryCollectionMember"/>
<method href="#addMediaCollectionMember"/>
</resource>

26
Learn with Passion!
JPassion.com

27