Overview of RESTful API Description Languages: Difference between revisions

Revision as of 04:58, 11 September 2015

Latest revision as of 06:59, 15 October 2024

(59 intermediate revisions by 43 users not shown)

Line 1:

'''RESTful''' (representational state transfer) '''API''' (application programming interface) '''DLs''' (description languages) are [[formal language]]s designed to provide a structured description of a [[REST]]ful [[web API]] that is useful both to a human and for automated machine processing. API description languages are sometimes called [[interface description language]]s (IDLs). The structured description might be used to generate documentation for human [[programmer]]s; 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.<ref>{{Cite book |last1=Zhai |first1=Juan |last2=Huang |first2=Jianjun |last3=Ma |first3=Shiqing |last4=Zhang |first4=Xiangyu |last5=Tan |first5=Lin |last6=Zhao |first6=Jianhua |last7=Qin |first7=Feng |title=Proceedings of the 38th International Conference on Software Engineering |chapter=Automatic model generation from documentation for Java API functions |date=2016-05-14 |chapter-url=https://doi.org/10.1145/2884781.2884881 |series=ICSE '16 |___location=New York, NY, USA |publisher=Association for Computing Machinery |pages=380–391 |doi=10.1145/2884781.2884881 |isbn=978-1-4503-3900-1|s2cid=2733669 }}</ref>

{{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 [[API]] that is useful both to a human and for automated machine processing. API Description Languages are sometimes called [[Interface Description Language]]s 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|WSDL 2.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">{{Cite web|url=http://www.slideshare.net/SOA_Software/api-description-languages|title = API Description Languages|date = 12 August 2014}}</ref>

==Principle==

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>

===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 [[Remote Procedure Call|RPC]] mechanisms.<ref>{{cite web|last1=Fielding|first1=Roy|title=REST APIs must be hypertext-driven|url=http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven|accessdate=4 November 2015}}</ref>

==List of RESTful API DLs==

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

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

*[[Web Services Description Language]] (WSDL)

*WSDL

*[[Hydra (specification)|Hydra]]

*WADL

*[[Open Data Protocol]] (OData)

*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

**http://barrister.bitmechanic.com/

==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.js|Ember]] Data

*JSON Schema

**used by Swagger, Google APIs Discovery,<ref>https://developers.google.com/discovery/v1/reference/apis</ref> 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.<ref name="slideshare.net"/>

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

|-

! style="width: 12em" |

! Sponsor

! Initial commit

! Latest stable release

! Stable release date

! Software license<ref name="license">Licenses here are a summary, and are not taken to be complete statements of the licenses. Some packages may use libraries under different licenses.</ref>

! Format

! Open Source

! Code generation (client)

! Code generation (server)

!

|-

| {{rh}} | [[RAML (software)|RAML]]

| [[MuleSoft]]

| September, 2013

|

|

|

| [[YAML]]

| {{Yes}}

|limited

| {{Yes}}

|

|-

| {{rh}} | [[API Blueprint]]

| [[Apiary]]

| April, 2013

|

|

|

| [[Markdown]]

| {{Yes}}

|

| {{Yes}}

|

|-

| {{rh}} | [[Swagger (computer science)|Swagger]]

| [[Reverb (company)]]

| July, 2011

|

|

|

| [[JSON]]

| {{Yes}}

| Yes

| {{Yes}}

|

|}

==References==

{{Reflist}}

==External links==

*[http://www.mayerdan.com/programming/2014/01/29/investigating-api-tooling/ Investigating Api Developer Tooling]

[[Category:Cloud standards]]

[[Category:Software architecture]]

{{software-stub}}