Overview of RESTful API Description Languages
 | This article is actively undergoing a major edit for a little while. To help avoid edit conflicts, please do not edit this page while this message is displayed. This page was last edited at 11:52, 14 March 2015 (UTC) (10 years ago) – this estimate is cached, . Please remove this template if this page hasn't been edited for a significant time. If you are the editor who added this template, please be sure to remove it or replace it with {{Under construction}} between editing sessions. |
RESTful (REpresentational State Transfer) API (Application Programming Interface) DLs (Description Languages) are formal languages designed to provide a structured description of an RESTful API that is useful both to a human and for automated machine processing. The structured description might be used to generate a documentation for human programmers; such documentation is easier to read than free-form document since every 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.
History
There are two previous mayor description languages, WSDL2.0 (Web Services Description Language) and WADL (Web Application Description Language). Neither is widely adopted in the industry for descibing RESTful APIs, citing poor human readability of both and WADL being actually unable to fully describe a RESTful API.[1]
List of RESTful API DLs
- WSDL
- WADL
- Swagger
- RAML
- Hypermedia
- API Blueprint
- IdDoos
Comparison of RESTful API DLs
The community around RESTful API DLs is vibrant and the landscape is still changing. According to a presentation by Akana, the most active projects in this area are Swagger, RAML and API Blueprint.[2]
| Sponsor | Initial commit | Latest stable release | Stable release date | Software license[3] | Open source | Format | Code generation (server) | Code generation (client) | Data backend | |
|---|---|---|---|---|---|---|---|---|---|---|
| RAML | Hallo Welt! - Medienwerkstatt GmbH | 31 March 2011 | 2.23.0 | 9 December 2014[4] | MediaWiki | GPL v2 | Yes | UTF-8 | Yes | PHP |
| API Blueprint | Hallo Welt! - Medienwerkstatt GmbH | 31 March 2011 | 2.23.0 | 9 December 2014[4] | MediaWiki | GPL v2 | Yes | UTF-8 | Yes | PHP |
| Swagger | Hallo Welt! - Medienwerkstatt GmbH | 31 March 2011 | 2.23.0 | 9 December 2014[4] | MediaWiki | GPL v2 | Yes | UTF-8 | Yes | PHP |
 | This software article is a stub. You can help Wikipedia by expanding it. |
- ^ http://www.slideshare.net/SOA_Software/api-description-languages
- ^ http://www.slideshare.net/SOA_Software/api-description-languages
- ^ Licenses here are a summary, and are not taken to be complete statements of the licenses. Some packages may use libraries under different licenses.
- ^ a b c "Changelog". help.blue-spice.org. Retrieved 2014-12-09.