RADL

REST API Description Language
Specification Version 1.0


RADL (pronounced “raddle”) is a specification for the description of a REST API. A RADL document may be in XML or JSON format. A schema is provided for XML, and an example is provided in JSON below.

The URL for the a RADL document may be included in a SCDL service description to direct a SIMS client device to the description of SCBP, SCTP, SCSP and other SIMS APIs for a particular service.

Each response must include radl as the first element with a version attribute (or child member in the case of JSON) indicating the specification version in the format #.#. See the RADL XML Schema for a complete specification of the RADL data structure.

RADL-DOC

RADL-DOC is a Javascript Library for auto-generating API documentation using RADL as the input data. Below is a link to example API documentation using RADL-DOC as well as a link to the RADL-DOC JavaScript Library file.

Example API Doc using RADL-DOC

RADL-DOC JavaScript Library

RADL XML Schema

Example RADL API Description in JSON:

{
  "radl": {
    "base": "/rest/v1",
    "params": [
      {
        "name": "output",
        "desc": "This sets the output format to JSON or XML.",
        "required": "no",
        "options": [ "json", "xml" ]
      }
    ],
    "responses": [
      {
        "name": "sctp",
        "desc": "This is the SCTP response format.",
        "outputs": [ "json", "xml" ],
        "schema": "http://simsapi.org/schemas/sctp.xsd",
        "element": "sctp"
      }
    ],
    "actions": [
      {
        "name": "capabilities",
        "desc": "Get the list of capabilities related to SCTP.",
        "url": "/capabilities",
        "methods": [ "get" ],
        "params": [ "output" ],  [A]
        "responses": [ "sctp" ]  [B]
      },
      {
        "name": "login",
        "desc": "Login to the service.",
        "url": "/sessions/create",
        "methods": [ "get", "post" ],
        "params": [  [C]
          {
            "name": "output"  [D]
          },
          {
            "name": "username"  [D]
          },
          {
            "name": "password"  [D]
          }
        ],
        "responses": [ "sctp" ]  [E]
      }
    ],
    "groups": [
      {
        "name": "User Acounts",
        "desc": "",
        "base": "",
        "actions": [ "login" ]  [F]
      },
      {
        "name": "Miscellaneous",
        "desc": "",
        "base": "",
        "actions": [
          {
            "name": "capabilities"  [G]
          }
        ]  [H]
      }
    ]
  }
}

Note: Defined values for each element are required to be understood. Additional vendor-specific values may be included using a “x_” prefix. A basic implementation is not required to support vendor-specific values.

[A] if an array element matches a globally defined param name, then insert child elements using global values

[B] if an array element matches a globally defined param name, then insert child elements using global values

[C] params and responses within an action can be expressed as an array of names (strings) or an array of objects

[D] if name matches a globally defined param, then any missing elements assume global values

[E] if an array element matches a globally defined response name, then insert child elements using global values

[F] if an array element matches a globally defined action name, then insert child elements using global values

[G] actions within in a group can be expressed as an array of names (strings) or an array of objects

[H] if an array element matches a globally defined action name, then insert child elements using global values