Describing REST services Ivo Malve

Using WSDL to describe REST APIs While WSDL is flexible in service binding options, it did not originally support HTTP operations other than GET and POST. Since REST services often use other HTTP verbs, such as PUT and DELETE, WSDL was a poor choice for documenting REST services. With version 2.0, WSDL supports all HTTP verbs and it is now considered to be an acceptable method of documenting REST services. LinkLink services-wsdl-and-wadl.html

The need for proper REST API documentation An increasing number of Web-based enterprises (Google, Yahoo, Amazon, Flickr to name but a few) are developing HTTP- based applications that provide programatic access to their internal data.

Textual documentation …Typically these applications are described using textual documentation that is sometimes supplemented with more formal specifications such as XML schema for XML-based data formats.

Examples of textual documentation Twitter APIs Flickr APIs Tesla Model S  Awesome example Awesome example examples.html

Web Application Description Language …WADL is designed to provide a machine process-able description of such HTTP-based Web applications. W3 WADL style

Summary WSDL  Flexible (binding to SMTP servers)  Complex WADL  Lightweight (no envelope)  Easier to understand  Easier to write  Sufficient for any web service XRD between-wsdl-2-0-wadl-xrd

Thank You! Questions?