This article may have been previously nominated for deletion: Wikipedia:Articles for deletion/Overview of RESTful API Description Languages exists. It is proposed that this article be deleted because of the following concern:
If you can address this concern by improving, copyediting, sourcing, renaming, or merging the page, please edit this page and do so. You may remove this message if you improve the article or otherwise object to deletion for any reason. Although not required, you are encouraged to explain why you object to the deletion, either in your edit summary or on the talk page. If this template is removed, do not replace it. This message has remained in place for seven days, so the article may be deleted without further notice. Find sources: "Overview of RESTful API Description Languages" – news · newspapers · books · scholar · JSTOR Nominator: Please consider notifying the author/project: {{subst:proposed deletion notify|Overview of RESTful API Description Languages|concern=[[WP:LISTCRUFT]] personified. This is no overview, it is a cobbled-together list of disparate [[Interface Description Language|IDL]] languages ([[Representational state transfer|REST]] is an irrelevance to these) that are cherry-picked because their back-end API might be [[RESTful]].
This article conveys nothing to the reader.}} ~~~~Timestamp: 20150908091252 09:12, 8 September 2015 (UTC) Administrators: delete |
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. API Description Languages are sometimes called Interface Description Languages 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 major description languages, WSDL2.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.[1]
List of RESTful API DLs
- WSDL
- WADL
- OData
- Swagger
- developer: Reverb, https://helloreverb.com/
- RAML
- developer: Mulesoft, http://www.mulesoft.com/
- Hypermedia
- API Blueprint
- I/O Docs
- developer: Mashery, http://www.mashery.com/
- Apache Avro
- Barrister
List of data description languages
A significant part of RESTful API description is the specification of returned data structures. The IDL might either specify its own format or use an existing data description format. A notable example which many RESTful API DLs use is JSON Schema.
- json:api
- http://jsonapi.org/
- Started as REST adapter for Ember Data
- JSON Schema
- used by Swagger, Google APIs Discovery,[2] I/O Docs
- Apache Avro
- https://avro.apache.org/
- both Interface Description Language and data description language
- JSON-RPC 2.0
- used by Barrister
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.[1]
| Sponsor | Initial commit | Latest stable release | Stable release date | Software license[3] | Format | Open Source | Code generation (client) | Code generation (server) | ||
|---|---|---|---|---|---|---|---|---|---|---|
| RAML | MuleSoft | September, 2013 | YAML | Yes | limited | Yes | ||||
| API Blueprint | Apiary | April, 2013 | Markdown | Yes | Yes | |||||
| Swagger | Reverb (company) | July, 2011 | JSON | Yes | Yes | Yes |
References
- ^ https://developers.google.com/discovery/v1/reference/apis
- ^ Licenses here are a summary, and are not taken to be complete statements of the licenses. Some packages may use libraries under different licenses.
External links
 | This software article is a stub. You can help Wikipedia by expanding it. |