MuleSoft Mastery: From Zero to Hero | Ch.5B

#%RAML 1.0 Library

# Published to Exchange as: com.example/shared-api-library/2.0.0
usage: |
  Central library for all com.example APIs.
  Import in any spec with:
    uses:
      Lib: exchange_modules/com.example/shared-api-library/2.0.0/library.raml

types:
  ApiResponse:  !include types/api-response.raml
  ErrorDetail:  !include types/error-detail.raml
  Pagination:   !include types/pagination.raml

traits:
  paginable:      !include traits/paginable.raml
  traceable:      !include traits/traceable.raml
  errorResponses: !include traits/error-responses.raml

securitySchemes:
  oauth2:    !include security/oauth2.raml
  clientId:  !include security/client-id-enforcement.raml

#%RAML 1.0 Trait
usage: Apply to every method that participates in end-to-end tracing.

headers:
  x-correlation-id:
    type: string
    description: |
      Client-generated UUID v4 identifying this request chain end-to-end.
      If absent, the API gateway MUST generate one and return it in responses.
      All downstream calls MUST forward this value unchanged.
    required: false
    pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
    example: "a4f8c1d2-3e5b-4789-9abc-0d1e2f3a4b5c"

responses:
  # RAML 1.0 does NOT support YAML anchors (&/*).
  # Each status code must be declared explicitly.
  200:
    headers:
      x-correlation-id:
        type: string
        description: Echo of the incoming x-correlation-id (or server-generated).
        example: "a4f8c1d2-3e5b-4789-9abc-0d1e2f3a4b5c"
  201:
    headers:
      x-correlation-id: { type: string, example: "a4f8c1d2-…" }
  400:
    headers:
      x-correlation-id: { type: string, example: "a4f8c1d2-…" }
  404:
    headers:
      x-correlation-id: { type: string, example: "a4f8c1d2-…" }
  500:
    headers:
      x-correlation-id: { type: string, example: "a4f8c1d2-…" }

#%RAML 1.0 DataType
displayName: ApiResponse
description: |
  Universal response envelope. Metadata fields always present.
  Data is populated on success, null on error.
type: object
properties:

  # ──────────── METADATA ─────────────────
  status:
    type: string
    enum: [ SUCCESS, ERROR ]
    required: true
    example: "SUCCESS"
  level:
    type: string
    enum: [ INFO, WARN, ERROR ]
    required: true
    example: "INFO"
  timestamp:
    type: datetime
    description: ISO 8601 UTC timestamp (server-assigned).
    required: true
    example: "2026-03-20T10:30:00Z"
  correlationId:
    type: string
    description: Echo of x-correlation-id header, or server-generated UUID.
    required: true
    pattern: ^[0-9a-fA-F-]{36}$
    example: "a4f8c1d2-3e5b-4789-9abc-0d1e2f3a4b5c"
  messages:
    type: ErrorDetail[]
    description: Empty [] on success. Multiple entries allowed (bulk validation).
    required: true
    example: []

  # ──────────── DATA ─────────────────────
  data:
    type: any
    description: |
      Business payload. Override with specific type at endpoint level:
        type: Customer | Customer[]
      Must be null when status = ERROR.
    required: false
    example: null

#%RAML 1.0 DataType
displayName: ErrorDetail
description: Single error or warning entry in messages[].
type: object
properties:
  code:
    type: string
    description: Domain-scoped code. Format {DOMAIN}-{4 digits}.
    required: true
    pattern: ^[A-Z]{2,8}-[0-9]{4}$
    example: "CUST-0001"
  description:
    type: string
    description: Human-readable summary — safe to show end users.
    required: true
    maxLength: 200
    example: "Customer not found"
  cause:
    type: string
    description: Technical root-cause for developers. Omit in production responses.
    required: false
    example: "No row for customers.id=99 in prod-db"
  field:
    type: string
    description: Request field that triggered the error. null if not field-specific.
    required: false
    example: "email"
  retryable:
    type: boolean
    description: Client hint — true if retrying might succeed.
    required: false
    default: false
    example: false

#%RAML 1.0 SecurityScheme
description: OAuth 2.0 — authorization_code and client_credentials grants.
type: OAuth 2.0
describedBy:
  headers:
    Authorization:
      description: Bearer token from the authorization server.
      type: string
      pattern: ^Bearer [A-Za-z0-9-._~+/]+=*$
      example: "Bearer eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyMSJ9.sig"
  responses:
    401:
      description: Token absent, expired, or invalid.
    403:
      description: Token valid but insufficient scope.
settings:
  authorizationUri: https://auth.example.com/oauth2/authorize
  accessTokenUri:   https://auth.example.com/oauth2/token
  authorizationGrants: [ authorization_code, client_credentials ]
  scopes: [ customers:read, customers:write, admin ]

#%RAML 1.0 SecurityScheme
description: |
  Client ID Enforcement — identifies the calling application.
  Credentials registered in Anypoint API Manager.
  Enforced by the "Client ID Enforcement" policy at the gateway.
type: Pass Through
describedBy:
  headers:
    client_id:
      type: string
      description: Application client ID from API Manager.
      required: true
      example: "a1b2c3d4e5f6a7b8c9d0e1f2"
    client_secret:
      type: string
      description: Application client secret.
      required: true
      example: "s3cr3tV4lu3x0y1z"
  responses:
    401:
      description: client_id or client_secret missing or unrecognized.
    403:
      description: Application known but not approved for this API.