Overview of RESTful API Description Languages

Last updated

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. [1]

Contents

History

There are two previous major description languages: WSDL 2.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. [2]

Principle

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 RPC mechanisms. [3]

List of RESTful API DLs

Related Research Articles

A web service (WS) is either:

An 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 are usually used to describe data types and interfaces in a language-independent way, for example, between those written in C++ and those written in Java.

Hypermedia, an extension of the term hypertext, is a nonlinear medium of information that includes graphics, audio, video, plain text and hyperlinks. This designation contrasts with the broader term multimedia, which may include non-interactive linear presentations as well as hypermedia. It is also related to the field of electronic literature. The term was first used in a 1965 article written by Ted Nelson.

In software engineering, the terms frontend and backend refer to the separation of concerns between the presentation layer (frontend), and the data access layer (backend) of a piece of software, or the physical infrastructure or hardware. In the client–server model, the client is usually considered the frontend and the server is usually considered the backend, even when some presentation work is actually done on the server itself.

In software engineering, service-oriented architecture (SOA) is an architectural style that focuses on discrete services instead of a monolithic design. By consequence, it is also applied in the field of software design where services are provided to the other components by application components, through a communication protocol over a network. A service is a discrete unit of functionality that can be accessed remotely and acted upon and updated independently, such as retrieving a credit card statement online. SOA is also intended to be independent of vendors, products and technologies.

REST is a software architectural style that was created to guide the design and development of the architecture for the World Wide Web. REST defines a set of constraints for how the architecture of a distributed, Internet-scale hypermedia system, such as the Web, should behave. The REST architectural style emphasises uniform interfaces, independent deployment of components, the scalability of interactions between them, and creating a layered architecture to promote caching to reduce user-perceived latency, enforce security, and encapsulate legacy systems.

The Web Services Invocation Framework (WSIF) supports a simple and flexible Java API for invoking any Web Services Description Language (WSDL)-described service.

A web framework (WF) or web application framework (WAF) is a software framework that is designed to support the development of web applications including web services, web resources, and web APIs. Web frameworks provide a standard way to build and deploy web applications on the World Wide Web. Web frameworks aim to automate the overhead associated with common activities performed in web development. For example, many web frameworks provide libraries for database access, templating frameworks, and session management, and they often promote code reuse. Although they often target development of dynamic web sites, they are also applicable to static websites.

XML Interface for Network Services (XINS) is an open-source technology for definition and implementation of internet applications, which enforces a specification-oriented approach.

<span class="mw-page-title-main">Web API</span> HTTP-based application programming interface used in web development

A web API is an application programming interface (API) for either a web server or a web browser. As a web development concept, it can be related to a web application's client side. A server-side web API consists of one or more publicly exposed endpoints to a defined request–response message system, typically expressed in JSON or XML by means of an HTTP-based web server. A server API (SAPI) is not considered a server-side web API, unless it is publicly accessible by a remote web application.

Scaffolding, as used in computing, refers to one of two techniques:

<span class="mw-page-title-main">Apache Axis2</span> Web service engine

Apache Axis2 is a web service engine. It is a redesign and re-write of the widely used Apache Axis SOAP stack. Implementations of Axis2 are available in Java and C.

The Web Application Description Language (WADL) is a machine-readable XML description of HTTP-based web services. WADL models the resources provided by a service and the relationships between them. WADL is intended to simplify the reuse of web services that are based on the existing HTTP architecture of the Web. It is platform and language independent and aims to promote reuse of applications beyond the basic use in a web browser. WADL was submitted to the World Wide Web Consortium by Sun Microsystems on 31 August 2009, but the consortium has no current plans to standardize it. WADL is the REST equivalent of SOAP's Web Services Description Language (WSDL), which can also be used to describe REST web services.

In software engineering, a resource-oriented architecture (ROA) is a style of software architecture and programming paradigm for supportive designing and developing software in the form of Internetworking of resources with "RESTful" interfaces. These resources are software components which can be reused for different purposes. ROA design principles and guidelines are used during the phases of software development and system integration.

ZK is an open-source Ajax Web application framework, written in Java, that enables creation of graphical user interfaces for Web applications with little required programming knowledge.

<span class="mw-page-title-main">Web Services Description Language</span> XML-based interface description language

The Web Services Description Language 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, which provides a machine-readable description of how the service can be called, what parameters it expects, and what data structures it returns. Therefore, its purpose is roughly similar to that of a type signature in a programming language.

Hypermedia as the engine of application state (HATEOAS) is a constraint of the REST application architecture that distinguishes it from other network application architectures.

<span class="mw-page-title-main">API</span> Software interface between computer programs

An application programming interface (API) is a way for two or more computer programs to communicate with each other. It is a type of software interface, offering a service to other pieces of software. A document or standard that describes how to build or use such a connection or interface is called an API specification. A computer system that meets this standard is said to implement or expose an API. The term API may refer either to the specification or to the implementation. Whereas a system's user interface dictates how its end-users interact with the system in question, its API dictates how to write code that takes advantage of that system's capabilities.

RESTful API Modeling Language (RAML) is a YAML-based language for describing static APIs. It provides all the information necessary to describe APIs on the level 2 of the Richardson Maturity Model. Although designed with RESTful APIs in mind, RAML is not capable of describing APIs that obey all constraints of REST. It encourages reuse, enables discovery and pattern-sharing and aims for merit-based emergence of best practices.

<span class="mw-page-title-main">Swagger (software)</span> Computing language

Swagger is a suite of tools for API developers from SmartBear Software and a former specification upon which the OpenAPI Specification is based.

References

  1. Zhai, Juan; Huang, Jianjun; Ma, Shiqing; Zhang, Xiangyu; Tan, Lin; Zhao, Jianhua; Qin, Feng (2016-05-14). "Automatic model generation from documentation for Java API functions". Proceedings of the 38th International Conference on Software Engineering. ICSE '16. New York, NY, USA: Association for Computing Machinery. pp. 380–391. doi:10.1145/2884781.2884881. ISBN   978-1-4503-3900-1. S2CID   2733669.
  2. "API Description Languages". 12 August 2014.
  3. Fielding, Roy. "REST APIs must be hypertext-driven" . Retrieved 4 November 2015.