Overview of RESTful API Description Languages
RESTful (representational state transfer) API (application programming interface) DLs (description languages) are formal languages designed to provide a structured description of a RESTful web API that is useful both to a human and for automated machine processing. API Description Languages are sometimes called interface description languages (IDLs). The structured description might be used to generate documentation for human programmers; 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.
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]
Alternatives
Hypertext-driven APIs
An alternative approach to 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 has been the original vision for RESTful APIs which distinguished them from RPC mechanisms.[2]
List of RESTful API DLs
- Web Services Description Language (WSDL)
- Web Application Description Language (WADL)
- CloudRail
- URL: http://cloudrail.com/
- developer: licobo GmbH
- Google Cloud Endpoints
- Open Data Protocol (OData)
- OASIS standard[3]
- URL: http://www.odata.org/
- developer: Microsoft
- OpenAPI Specification
- URL: https://openapis.org/
- developer: Open API Initiative (OAI), originally developed as "Swagger" specification by Wordnik, SmartBear Software
- RESTful Service Description Language (RSDL)
- URL: http://www.balisage.net/Proceedings/vol10/html/Robie01/BalisageVol10-Robie01.html
- developer: Michael Pasternak
- Hydra Core Vocabulary (Hydra)
- URL: http://www.hydra-cg.com/spec/latest/core/
- developer: Hydra W3C Community Group, http://www.hydra-cg.com/
- RESTful API Modeling Language (RAML)
- URL: http://raml.org/
- developer: Mulesoft, http://www.mulesoft.com/
- Hypermedia
- API Blueprint
- URL: https://apiblueprint.org/
- developer Apiary, https://apiary.io/company
- API Builder
- URL: https://www.apibuilder.io/
- developers: HBC, Flow Commerce
- I/O Docs
- URL: https://github.com/mashery/iodocs
- developer: Mashery, http://www.mashery.com/
- Apache Avro
- Barrister
- URL: http://barrister.bitmechanic.com/
- developer: James Cooper[4]
- SERIN - Semantic Restful Interfaces[5]
- URL: http://www.semanticinterface.org
- developers: Bruno Muniz, Hermano Lira, José Renato Villela Dantas, Tadeu Nunes, Laura Chaves, Julio Cesar Campos Neto, Pedro Porfírio Muniz Farias
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 OpenAPI, Google APIs Discovery,[6] 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 active and the landscape is still changing. According to a presentation by Akana, the most active projects in this area are OpenAPI, RAML and API Blueprint.[1]
| Sponsor | Initial commit | Latest stable release | Stable release date | Software license[7] | Format | Open Source | Code generation (client) | Code generation (server) | |
|---|---|---|---|---|---|---|---|---|---|
| RAML | MuleSoft | September, 2013 | 1.0 | May 16, 2016 | Apache 2.0 | YAML | Yes | Yes | Yes |
| API Blueprint | Apiary | April, 2013 | MIT | Markdown | Yes | No | No | ||
| OpenAPI | Open API Initiative (OAI) | July, 2011 | 3.0 | July 26, 2017 | Apache 2.0 | JSON or YAML | Yes | Yes | Yes |
| SERIN | UNIFOR | 2011 | 2.0 | December 2014 | Creative Commons | RDF | Yes | No | Yes |
Frameworks
Many server frameworks interoperate with one or more IDLs.
- Gugamarket REST API framework
- IDLs: OpenAPI
- URL: https://pliik.github.io/gugamarket/
- developer: https://github.com/pliik
References
- ^ Fielding, Roy. "REST APIs must be hypertext-driven". Retrieved 4 November 2015.
- ^ "OASIS Open Data Protocol (OData) TC - OASIS".
- ^ "Barrister RPC - About".
- ^ Lira, Hermano Albuquerque; Dantas, Jose Renato Villela; Muniz, Bruno de Azevedo; Nunes, Tadeu Matos; Farias, Pedro Porfirio Muniz (2015-01-01). "An Approach to Support Data Integrity for Web Services Using Semantic RESTful Interfaces". Proceedings of the 24th International Conference on World Wide Web. WWW '15 Companion. New York, NY, USA: ACM: 1485–1490. doi:10.1145/2740908.2743042. ISBN 9781450334730.
- ^ 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.