WADL

This post will bring some information about WADL, what is it, how to read it and why we should create this document when publishing company API's.

So what is it WADL ….

Web Application Description Language – an XML based file format that provides a description of HTTP-based web applications, most known are: REST web services. WADL is the way to explicit your methods , headers and parameters in one readable format.

Here is the explanation of WADL by WIKI :

“The purpose of WADL is to allow services on the Internet (or any other IP network) to be described in a machine processable way, to make it easier to create Web 2.0 style applications and create a dynamic way of creating and configuring services. Prior to this, it was necessary to go to an existing web service, study it and write the application manually. WADL can be thought of as the REST equivalent of Web Services Description Language version 1.1. WADL models the resources provided by a service, and the relationships between them.”

For this post we choose the D&B REST API.

Here is the full WADL document you can download and try dnbDnBAPI-10 

Let's take a look on the example 

<application xmlns="http://research.sun.com/wadl/2006/10">
  .....
    <resources base="http://dnbdirect-sandbox.dnb.com/DnBAPI-10/rest">
        <resource path="/">
            ..........              
            <resource path="search/company">
                ........               
                <resource path="/">
                    <resource path="{keyword}">
                        <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" name="keyword"/>
                        <method name="POST" id="findCompanyJSONRequest"/>                         
                        <method name="GET" id="findCompany">
                            <request>
                                <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:long" style="query" name="duns_from"/>
                                <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:long" style="query" name="duns_to"/>
                                .......
                            </request>
                            <response>
                                <representation mediaType="application/json;charset=UTF-8"/>
                            </response>
                        </method>
                    </resource>
                </resource>                 
            .........       
        </resource>
    </resources>
</application>

So, what we are getting here:

This service is described using a set of resource elements. Each of these contains parameter elements to describe the inputs, and method elements which describe the request and response of a resource. The request element specifies how to represent the input, what types are required.
The result of the following representation looks like this:

http://dnbdirect-sandbox.dnb.com/DnBAPI-10/rest/search/company/{keyword}

Actually it is an API url to search companies by keyword where {keyword}  -  is search query and it is string.
 

This REST service can be used by both GET and POST methods, look at parameter element name. Using of POST it reaches “findCompanyJSONRequest” function and GET method will reach “findCompany”. The code also shows that both of them can get response parameters and will return the same structure result.

The example environment has more than one version , it known , based on two different WADL documents.The second WADL document you can get from here ( dnbDnBAPI-11). Compare them and you’ll find the differences.

In conclusion :

WADL will help you :

·         to versioning your REST API

·         to make your REST API clear and readable

·         to reduce your customer service expenses.

Good Luck!!