Module 2 of 7

API Design with RAML & OAS

Learn to write clean, versioned API specifications using RAML 1.0 and OAS 3.0, leverage API fragments for reuse, and mock your API for early consumer feedback.

3 lessons~3 hours

RAML 1.0 Fundamentals

RAML (RESTful API Modeling Language) is a YAML-based language for describing REST APIs clearly and concisely.

A RAML file begins with the version header `#%RAML 1.0` and a set of root-level properties: title, version, baseUri, and mediaType. Resources are declared with a `/path` key, and HTTP methods are nested under them.

RAML supports data types, traits (reusable method behaviour like pagination), resource types (reusable resource patterns), and libraries. These features eliminate repetition and make large API specs maintainable.

MuleSoft's API Designer in Design Center provides a live preview and mock server from your RAML spec — no code required.

orders-api.ramlyaml

#%RAML 1.0
title: Orders API
version: v1
baseUri: https://api.acme.com/{version}
mediaType: application/json

types:
  Order:
    type: object
    properties:
      orderId:   string
      customer:  string
      amount:    number
      status:    string

/orders:
  get:
    description: Retrieve all orders
    queryParameters:
      status:
        type: string
        required: false
    responses:
      200:
        body:
          application/json:
            type: Order[]
  post:
    description: Create a new order
    body:
      application/json:
        type: Order
    responses:
      201:
        description: Order created

OAS 3.0 Essentials

OpenAPI Specification 3.0 is the industry-standard format for REST API documentation and is supported natively by Anypoint Platform.

OAS 3.0 uses YAML or JSON. The key sections are `info`, `servers`, `paths`, `components` (for reusable schemas, responses, and parameters), and `security`.

Anypoint Platform can import OAS 3.0 specs and auto-generate a Mule scaffolding project — saving hours of boilerplate setup.

When working with external consumers (especially those outside MuleSoft ecosystems), OAS is often preferred because of wider tooling support (Swagger UI, Postman, etc.).

orders-api.yaml (OAS 3.0)yaml

openapi: 3.0.0
info:
  title: Orders API
  version: 1.0.0
servers:
  - url: https://api.acme.com/v1
paths:
  /orders:
    get:
      summary: List orders
      parameters:
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
components:
  schemas:
    Order:
      type: object
      properties:
        orderId:  { type: string }
        customer: { type: string }
        amount:   { type: number }
        status:   { type: string }

API Fragments & Mocking

Fragments let you extract reusable types, traits, and security schemes into separate files that are shared across multiple APIs.

Common fragment types include: DataType (shared schemas), Trait (reusable query params, headers, responses), ResourceType, SecurityScheme, and Library. Store them in Exchange so all teams can discover and depend on them.

A mock service generated from your RAML or OAS spec lets front-end and integration teams build against the contract before the real implementation exists — cutting parallel development time significantly.

MuleSoft's Design Center mocking service is available instantly from the editor. You can also use the API Notebook feature to document and test API calls interactively.

fragments/pagination-trait.ramlyaml

#%RAML 1.0 Trait
queryParameters:
  page:
    type: integer
    default: 1
    minimum: 1
  pageSize:
    type: integer
    default: 20
    maximum: 100
responses:
  200:
    headers:
      X-Total-Count:
        type: integer

Previous module

Anypoint Platform Fundamentals

Next module

Building Mule Flows & Connectors