RESTful (representational state transfer) API (application programming interface) DLs (description languages) are

formal language In logic, mathematics, computer science, and linguistics, a formal language consists of words whose letters are taken from an alphabet and are well-formed according to a specific set of rules. The alphabet of a formal language consists of s ...

s designed to provide a structured description of a

REST Rest or REST may refer to: Relief from activity * Sleep ** Bed rest * Kneeling * Lying (position) * Sitting * Squatting position Structural support * Structural support ** Rest (cue sports) ** Armrest ** Headrest ** Footrest Arts and ente ...

ful

web API A web API is an application programming interface for either a web server or a web browser. It is a web development concept, usually limited to a web application's client-side (including any web frameworks being used), and thus usually does not i ...

that is useful both to a human and for automated machine processing. API description languages are sometimes called

interface description language interface description language or interface definition language (IDL), is a generic term for a language that lets a program or object written in one language communicate with another program written in an unknown language. IDLs describe an inter ...

s (IDLs). The structured description might be used to generate documentation for human

programmer A computer programmer, sometimes referred to as a software developer, a software engineer, a programmer or a coder, is a person who creates computer programs — often for larger computer software. A programmer is someone who writes/creates ...

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.

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.

Principle

Hypertext-driven API

The principle behind building RESTful APIs is known under the acronym HATEOAS (

Hypermedia as the Engine of Application State Hypermedia as the Engine of Application State (HATEOAS) is a constraint of the REST application architecture that distinguishes it from other network application architectures. With HATEOAS, a client interacts with a network application whose ap ...

). 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 Roy Thomas Fielding (born 1965) is an American computer scientist, one of the principal authors of the HTTP specification and the originator of the Representational State Transfer (REST) architectural style. He is an authority on computer network ...

's doctoral thesis ''Architectural Styles and the Design of Network-based Software Architectures''. HATEOAS is one of the key elements distinguishing REST from

RPC RPC may refer to: Science and technology * Rational polynomial coefficient * Reactive Plastic Curtain, a carbon-dioxide-absorbing device used in some rebreather breathing sets * Regional Playback Control, a regional lockout technology for DVDs * ...

mechanisms.

List of RESTful API DLs

Web Services Description Language The Web Services Description Language (WSDL ) is an XML-based interface description language that is used for describing the functionality offered by a web service. The acronym is also used for any specific WSDL description of a web service (also ...

(WSDL) * Hydra *

Open Data Protocol In computing, Open Data Protocol (OData) is an open protocol that allows the creation and consumption of queryable and interoperable REST APIs in a simple and standard way. Microsoft initiated OData in 2007. Versions 1.0, 2.0, and 3.0 are relea ...

(OData)

References

{{Reflist

External links

Investigating Api Developer Tooling
Cloud standards Software architecture