Overview of RESTful API Description Languages

RESTful (representational state transfer) API (application programming interface) DLs (description languages) are formal languages designed to provide a structured description of a RESTful web API that is useful both to a human and for automated machine processing. API description languages are sometimes called interface description languages (IDLs). The structured description might be used to generate documentation for human programmers; such documentation may be easier to read than free-form documentation, since all documentation generated by the same tool follows the same formatting conventions. Additionally, the description language is usually precise enough to allow automated generation of various software artifacts, like libraries, to access the API from various programming languages, which takes the burden of manually creating them off the programmers.^[1]

History

There are two previous major description languages: WSDL 2.0 (Web Services Description Language) and WADL (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.^[2]

Principle

Hypertext-driven API

The principle behind building RESTful APIs is known under the acronym HATEOAS (Hypermedia as the Engine of Application State). 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 Roy Fielding's doctoral thesis Architectural Styles and the Design of Network-based Software Architectures. HATEOAS is one of the key elements distinguishing REST from RPC mechanisms.^[3]

List of RESTful API DLs

Web Services Description Language (WSDL)
Hydra
Open Data Protocol (OData)

References

^ 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.
^ "API Description Languages". 12 August 2014.
^ Fielding, Roy. "REST APIs must be hypertext-driven". Retrieved 4 November 2015.

[1] 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.

[slideshare.net-2] "API Description Languages". 12 August 2014.

[3] Fielding, Roy. "REST APIs must be hypertext-driven". Retrieved 4 November 2015.

[1]

[2]

[3]