Standard REST endpoints can utilize established documentation tools rather than Word or Excel. This post introduces spec-driven development using REST standards like RAML with Oracle ORDS.

## The Problem with Traditional Approaches

Traditional design documents led to misalignments between service builders and consumers. Specifications in Word documents or spreadsheets often became outdated, incomplete, or ambiguous.

Spec-driven approaches enable iteration before coding begins. Tools can auto-generate mock endpoints from specifications, allowing real testing without implementation.

## REST API Standards Compared

Three prominent standards exist for REST API specification:

### Swagger (OpenAPI)

- Wide adoption
- Strong tooling ecosystem
- Oracle is using Swagger based on their API catalog
- JSON or YAML format

### RAML (RESTful API Modeling Language)

- Clean, readable syntax
- Strong reusability features
- Backed by MuleSoft
- YAML-based

### API Blueprint

- Markdown-based
- Focus on documentation
- Simple syntax
- Good for getting started

## Why I Chose RAML

After reading “Undisturbed REST” by Michael Stowe, I was drawn to RAML for several reasons:

- **Easy to understand markup** \- YAML syntax is clean and readable
- **Generates clean documentation** \- Auto-generated docs look professional
- **Auto-generates mock endpoints** \- Test APIs before implementation
- **Reusability** \- Traits and data types reduce duplication

## RAML Benefits in Detail

### Traits

Define common patterns once and reuse them:

```
traits:
  paginated:
    queryParameters:
      offset:
        description: Number of items to skip
        type: integer
        default: 0
      limit:
        description: Maximum items to return
        type: integer
        default: 25
```

### Data Types

Define schemas once, use everywhere:

```
types:
  Customer:
    properties:
      id: integer
      name: string
      email: string
      created: datetime
```

### Resource Types

Create templates for common resource patterns:

```
resourceTypes:
  collection:
    get:
      description: Get all <<resourcePathName>>
      responses:
        200:
          body:
            application/json:
              type: <<item>>[]
```

## Tools and Resources

### Design Tools

**MuleSoft Anypoint Platform**

A cloud-based API design platform with RAML editor, mocking service, and developer portal generation.

**API Workbench (Atom Package)**

A free Atom package for local RAML development with syntax highlighting and validation.

### Developer Portal Generation

RAML tools can generate interactive documentation where developers can try APIs directly.

### Learning Resources

- **RAML 100 & 200 Tutorials** \- Official getting started guides
- **Undisturbed REST Workshop** \- 10-part video series by Michael Stowe
- **GitHub RAML APIs Repository** \- Example RAML specifications

## Applying RAML to ORDS

While ORDS doesn’t natively consume RAML, the spec-driven approach still provides value:

1. **Design first** \- Create RAML specification
2. **Generate documentation** \- Share with consumers early
3. **Mock endpoints** \- Allow consumer testing
4. **Implement in ORDS** \- Build handlers matching the spec
5. **Validate** \- Ensure implementation matches specification

## Conclusion

Spec-driven development with RAML brings discipline to REST API design. Whether you choose RAML, Swagger, or API Blueprint, the key is designing and documenting APIs before implementation.

* * *

Jon Dixon, Co-Founder JMJ Cloud