Describing Java-based APIs with RADL

People build REST APIs in different ways:

• Code-driven
  Start by writing code to implement the REST API. Extract a RADL description from the code and manually fill in the missing pieces. Then generate documentation from RADL.
• Design-driven
  Describe the API in RADL. Generate code and documentation from RADL. There are a couple of variations of this approach:
  • Requirements-driven
    Start with the requirements in the form of a state diagram that captures the interactions and then describe the data.
  • Schema-driven
    Start with an (industry standard) schema of the data. These schemas are usually foreordained (the user cannot change them) and orthogonal to REST semantics.
  • Examples-driven
    Start with examples that explain the structure of the data.

RADL Tooling supports all of these styles. However you choose to use RADL for your Java-based REST API, you'll probably want to automate the process.

Code-Driven

In the code-driven style, code is written first and then a partial RADL file is extracted from the source code. The API designer then manually adds the missing pieces, like the state diagram. RADL validation can help you by pointing out those missing pieces. Whenever the code changes, you can re-run the extraction, and it will keep the information you added.

For more details, see Extracting RADL From Java Code.

Design-Driven

In the design-driven style the API designer manually creates a RADL file and then generates code from it, or codes by hand (perhaps based on documentation generated from the RADL file).

For more details, see Generating Java Code from RADL.