MuleSoft Designing APIs in RAML

RAML stands for RESTful API Modeling Language. It is a way to describe what your API does before you write any code. RAML is like an architectural blueprint for a building — you plan every room, door, and window on paper before construction begins. Designing the API first helps teams agree on the interface early and reduces rework later.

Why Design First

When a developer builds an API without a design, the consumer (a mobile app or another service) has to wait for the API to be finished before they can start their work. With a RAML design, the consumer team gets the API specification upfront. They build and test their code against a mock server while the API developer builds the real implementation in parallel. Both teams finish at the same time.

Parallel Development with RAML

Week 1:
  API Team: Writes RAML spec in Design Center
  Consumer Team: Reviews and approves RAML

Week 2-4:
  API Team:      Builds real Mule API from RAML
  Consumer Team: Builds mobile app using RAML mock server
                (mock server auto-generated from RAML)

Week 5:
  Integration Testing: Connect mobile app to real API.
  Works immediately because both sides followed the RAML spec.

RAML File Structure

A RAML file starts with a version declaration and basic API information, then defines the endpoints (resources) and their operations.

Minimal RAML File

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

/orders:
  get:
    description: Returns a list of all orders
    responses:
      200:
        body:
          example: |
            [
              { "id": "ORD-001", "customer": "Alice", "total": 150.00 },
              { "id": "ORD-002", "customer": "Bob",   "total": 89.50  }
            ]
  post:
    description: Creates a new order
    body:
      example: |
        { "customer": "Carol", "items": ["Pen", "Book"], "total": 15.50 }
    responses:
      201:
        body:
          example: |
            { "id": "ORD-003", "status": "created" }

/orders/{orderId}:
  get:
    description: Returns a specific order by ID
    responses:
      200:
        body:
          example: |
            { "id": "ORD-001", "customer": "Alice", "total": 150.00 }
      404:
        body:
          example: |
            { "error": "Order not found" }

RAML Data Types

Data types in RAML define the structure of request and response bodies. They act like contracts — you specify exactly what fields are expected and what type each field should be.

Defining a Data Type

#%RAML 1.0
title: Customer API
version: v1

types:
  Customer:
    type: object
    properties:
      id:
        type: string
        required: true
        example: "CUST-001"
      name:
        type: string
        required: true
        minLength: 2
        maxLength: 100
        example: "Alice Smith"
      email:
        type: string
        required: true
        pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
        example: "alice@example.com"
      age:
        type: integer
        minimum: 18
        maximum: 120
        required: false

/customers:
  post:
    body:
      type: Customer       # References the Customer type
    responses:
      201:
        body:
          type: Customer

RAML Traits: Reusable Behaviors

A trait is a reusable behavior that you apply to multiple operations. Common traits include pagination, authentication headers, and error responses. Define a trait once and apply it to many endpoints.

Trait Example: Pagination

traits:
  paginated:
    queryParameters:
      page:
        type: integer
        default: 1
        description: Page number to return
      pageSize:
        type: integer
        default: 20
        maximum: 100
        description: Number of records per page

/customers:
  get:
    is: [paginated]      # Applies the paginated trait
    responses:
      200:
        body:
          example: |
            { "data": [...], "page": 1, "pageSize": 20, "total": 350 }

/orders:
  get:
    is: [paginated]      # Same trait reused here

RAML Resource Types: Reusable Endpoint Patterns

Resource types let you define a template for an endpoint pattern and reuse it across many resources. The "collection" pattern (GET list + POST create) and the "item" pattern (GET by ID + PUT update + DELETE) repeat constantly in REST APIs.

resourceTypes:
  collection:
    get:
      responses:
        200:
          body:
            type: array
    post:
      responses:
        201:
          body:
            type: object

/customers:
  type: collection       # GET /customers returns array, POST creates one
  
/products:
  type: collection       # Same pattern reused here

Using Design Center to Write RAML

MuleSoft's Design Center provides a browser-based RAML editor. You get syntax highlighting, auto-completion, and a live API Console on the right side. The Console shows your API's endpoints and lets you send test requests to the mock server.

Steps to create an API in Design Center:

1. Log in to Anypoint Platform and open Design Center
2. Click Create New and select New API Specification
3. Enter the API name and choose RAML 1.0
4. Write your RAML specification in the editor
5. Click Publish to Exchange when the design is ready

Importing RAML into Anypoint Studio

After publishing the RAML to Anypoint Exchange, you scaffold the Mule implementation from the design in Anypoint Studio. Go to File > New > Mule Project and check Import from Exchange. Studio generates the skeleton flows and HTTP Listener configurations from the RAML automatically, saving hours of setup work.