RADL

RESTful API Description Language (RADL) is an XML vocabulary for describing Hypermedia-driven RESTful APIs. Unlike most HTTP API description languages, RADL focuses on defining a truly hypermedia-driven REST API from the client's point of view. Unlike description languages based on JSON or Markdown, RADL makes it easy to integrate documentation written in HTML or XML. The APIs that RADL describes may use any media type, in XML, JSON, HTML, or any other format.

RADL can be used to:

• Design a RESTful API
• Validate an API description for consistency
• Generate documentation from an API description
• Generate Spring Framework Java controller classes from an API description (for design-first environments)
• Generate the resource model for a RESTful API from Spring Framework of JAX-RS Java controller classes (for code-first environments)

NOTE - RADL can be used to design RESTful APIs, validate them for consistency, or generate documentation for any environment. It cannot currently generate controllers for non-Java environments like Node.js or generate resource models from source code in these environments, and we have not yet defined a timeline for doing so. If you need support for a particular environment in RADL, please contact the authors - we welcome contributed code to support such environments.

RADL describes both the hypermedia client API and the resource model, which describes the implementation and should not be exposed to the client. The client API is defined in terms of client states, link relations, media types, URI parameters, and any custom headers or status codes that need to be documented.

The resource model is defined in terms of resources, their locations, the HTTP methods that can be applied to them, and the conventions for using those methods. The resource model corresponds roughly to the information found in Swagger or RAML.

In documentation generated by RADL, the interfaces associated with each client state are assembled from the client API description and the resource model.