Overview of RESTful API Description Languages: Difference between revisions

Revision as of 02:04, 30 November 2015

Revision as of 02:07, 30 November 2015

Line 1:

{{Orphan|date=March 2015}}

'''''RESTful''''' (REpresentational State Transfer) '''''API''''' (Application Programming Interface) '''''DLs''''' (Description Languages) are [[formal language]]s designed to provide a structured description of an [[REST]]ful [[web API]] that is useful both to a human and for automated machine processing. API Description Languages are sometimes called [[Interfaceinterface Descriptiondescription Languagelanguage]]s (IDLs). The structured description might be used to generate a documentation for human [[programmer]]s; 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, [[Web Services Description Language|WSDL2.0]] (Web Services Description Language) and [[Web Application Description Language|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.<ref name="slideshare.net">http://www.slideshare.net/SOA_Software/api-description-languages</ref>

== Alternatives ==

===Hypertext-driven APIs===

Line 13 ⟶ 12:

==List of RESTful API DLs==

<!-- TODO: make it a table -->

<!-- Name, URL, Developer, Note, Refs -->

Line 48 ⟶ 46:

==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/

Line 61 ⟶ 58:

==Comparison of RESTful API DLs==

The community around RESTful API DLs is vibrant{{citation needed|date=September 2015}} 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.<ref name="slideshare.net"/>

{| class="wikitable sortable" style="text-align: center; font-size: 85%; width: auto; table-layout: fixed;"

|-

Line 117 ⟶ 112:

== Frameworks ==

Many server frameworks interoperate with one or more IDLs.

*Gugamarket REST API framework

**IDLs: Swagger