Spec Driven REST with Oracle ORDS and RAML

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