Overview of RESTful API Description Languages

<h2 id="history">History</h2>
<p>There are two previous major description languages: <a href="/facts/Web_Services_Description_Language/tQPIot4A">WSDL 2.0</a> (Web Services Description Language) and <a href="/facts/Web_Application_Description_Language/ao6xnzMK">WADL</a> (Web Application Description Language). Neither is widely adopted in the industry for describing RESTful APIs, citing poor human readability of both and WADL being actually unable to fully describe a RESTful API.<a class="footnote-ref" id="fnref:2" href="#fn:2"><sup>2</sup></a>
</p>
<h2 id="principle">Principle</h2>
<h3>Hypertext-driven API</h3>
<p>The principle behind building RESTful APIs is known under the acronym HATEOAS (<a href="/facts/Hypermedia_as_the_Engine_of_Application_State/F7d9d2M8">Hypermedia as the Engine of Application State</a>). In this approach, the client software is not written to a static interface description shared through documentation. Instead, the client is given a set of entry points and the API is discovered dynamically through interaction with these endpoints. HATEOAS was introduced in <a href="/facts/Roy_Fielding/Arp1Qy5X">Roy Fielding</a>'s doctoral thesis <i>Architectural Styles and the Design of Network-based Software Architectures</i>. HATEOAS is one of the key elements distinguishing REST from <a href="/facts/Remote_Procedure_Call/uMMb9CQw">RPC</a> mechanisms.<a class="footnote-ref" id="fnref:3" href="#fn:3"><sup>3</sup></a>
</p>
<h2 id="list-of-restful-api-dls">List of RESTful API DLs</h2>
<ul><li><a href="/facts/Web_Services_Description_Language/tQPIot4A">Web Services Description Language</a> (WSDL)</li>
<li>Hydra</li>
<li><a href="/facts/Open_Data_Protocol/kSK4B2Ye">Open Data Protocol</a> (OData)</li></ul>

<h2 id="references">References</h2>

<ol>
<li id="fn:1"><p>Zhai, Juan; Huang, Jianjun; Ma, Shiqing; Zhang, Xiangyu; Tan, Lin; Zhao, Jianhua; Qin, Feng (2016-05-14). "Automatic model generation from documentation for Java API functions". Proceedings of the 38th International Conference on Software Engineering. ICSE '16. New York, NY, USA: Association for Computing Machinery. pp. 380–391. doi:10.1145/2884781.2884881. ISBN 978-1-4503-3900-1. S2CID 2733669. <a href="978-1-4503-3900-1" target="_blank">978-1-4503-3900-1</a> <a href="#fnref:1" class="footnote-back-ref">↩</a></p></li>
<li id="fn:2"><p>"API Description Languages". 12 August 2014. <a href="https://www.slideshare.net/SOA_Software/api-description-languages" target="_blank">https://www.slideshare.net/SOA_Software/api-description-languages</a> <a href="#fnref:2" class="footnote-back-ref">↩</a></p></li>
<li id="fn:3"><p>Fielding, Roy. "REST APIs must be hypertext-driven". Retrieved 4 November 2015. <a href="http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven" target="_blank">http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven</a> <a href="#fnref:3" class="footnote-back-ref">↩</a></p></li>
</ol>

Overview of RESTful API Description Languages open-in-new

Overview of RESTful API Description Languages