Describing REST services
Explore the evolution of REST API documentation methods, from the limitations of WSDL to the emergence of more suitable approaches like WADL. Discover the importance of proper documentation for REST services and learn about textual documentation examples from popular APIs like Twitter and Flickr. Gain insights into the advantages of WADL in describing HTTP-based web applications. Compare the characteristics of WSDL and WADL to determine the best fit for your API documentation needs.
Download Presentation
Please find below an Image/Link to download the presentation.
The content on the website is provided AS IS for your information and personal use only. It may not be sold, licensed, or shared on other websites without obtaining consent from the author.If you encounter any issues during the download, it is possible that the publisher has removed the file from their server.
You are allowed to download the files provided on this website for personal or commercial use, subject to the condition that they are used lawfully. All files are the property of their respective owners.
The content on the website is provided AS IS for your information and personal use only. It may not be sold, licensed, or shared on other websites without obtaining consent from the author.
E N D
Presentation Transcript
Describing REST services Ivo Malve 23.03.2015
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. http://rest.elkstein.org/2008/02/documenting-rest- services-wsdl-and-wadl.html With version 2.0, WSDL supports all HTTP verbs and it is now considered to be an acceptable method of documenting REST services. Link
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. http://www.w3.org/Submission/wadl/
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. http://www.w3.org/Submission/wadl/
Examples of textual documentation Twitter APIs Flickr APIs Tesla Model S Awesome example http://rest.elkstein.org/2008/02/real-rest- 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 http://www.w3.org/Submission/wadl/
Summary WSDL Flexible (binding to SMTP servers) Complex http://stackoverflow.com/questions/2215646/difference- WADL Lightweight (no envelope) Easier to understand Easier to write Sufficient for any web service between-wsdl-2-0-wadl-xrd XRD
Thank You! Questions?
