Wikipedia

Overview of RESTful API Description Languages

This is an old revision of this page, as edited by Wieno (talk | contribs) at 06:18, 10 May 2015 (Added {{merge to}} tag to article (TW)). The present address (URL) is a permanent link to this revision, which may differ significantly from the current revision.

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 mayor 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

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
  • JSON Schema
    • used by Swagger, Google APIs Discovery,[2] I/O Docs
  • Apache Avro
  • 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

  1. ^ a b http://www.slideshare.net/SOA_Software/api-description-languages
  2. ^ https://developers.google.com/discovery/v1/reference/apis
  3. ^ Licenses here are a summary, and are not taken to be complete statements of the licenses. Some packages may use libraries under different licenses.


 

This software article is a stub. You can help Wikipedia by expanding it.

Retrieved from "https://en.wikipedia.org/w/index.php?title=Overview_of_RESTful_API_Description_Languages&oldid=661659345"