Durante años, RAML (RESTful API Modeling Language) fue el estándar de facto para diseñar APIs en el ecosistema MuleSoft — fue de hecho una creación de la propia MuleSoft. Pero el mercado se movió hacia OpenAPI Specification (OAS), y con la edición 2026 del temario y la llegada de Anypoint Code Builder, OAS 3.0 pasó a ser el formato que se recomienda por defecto para proyectos nuevos.
Esto no es un simple cambio de sintaxis. Cambia cómo piensas el diseño de una API antes de escribir una sola línea de flujo.
Por qué OAS y no RAML, a estas alturas
- Adopción de mercado: la inmensa mayoría de herramientas de terceros (Postman, Swagger, gateways de API de otros proveedores) hablan OAS de forma nativa. RAML quedó como un estándar casi exclusivo de MuleSoft.
- Tooling de Anypoint Code Builder: el editor visual de diseño de API en Code Builder genera OAS por defecto. Puedes seguir importando RAML, pero el flujo «camino feliz» ya no pasa por ahí.
- Legibilidad para no-desarrolladores: OAS en JSON o YAML es más fácil de leer para un product owner o un arquitecto de negocio que RAML, que tiene su propia sintaxis con indentación estricta.
Estructura básica de un documento OAS 3.0
openapi: 3.0.3
info:
title: American Flights API
version: 1.0.0
paths:
/flights/{flightId}:
get:
summary: Obtiene el detalle de un vuelo
parameters:
- name: flightId
in: path
required: true
schema:
type: string
responses:
'200':
description: Vuelo encontrado
content:
application/json:
schema:
$ref: '#/components/schemas/Flight'
components:
schemas:
Flight:
type: object
properties:
id:
type: string
origin:
type: string
destination:
type: string
Las diferencias clave con RAML que notarás de inmediato:
| Concepto | RAML | OAS 3.0 |
|---|---|---|
| Definición de tipos | types: |
components/schemas |
| Ejemplos | example: inline |
examples: con referencias |
| Seguridad | securitySchemes (similar) |
components/securitySchemes |
| Reutilización | traits |
parameters y responses reutilizables en components |
Diseñar primero, programar después: el flujo API-first
El valor real de OAS no es la sintaxis, es forzarte a diseñar el contrato de la API antes de tocar un flujo Mule. El orden correcto en Anypoint Code Builder es:
- Define los endpoints, parámetros y esquemas de respuesta en el documento OAS.
- Valida el contrato con el equipo consumidor (frontend, otro sistema, partner externo) antes de implementar nada.
- Genera el scaffold del flujo Mule (el conector APIkit) directamente desde el OAS ya validado.
- Implementa la lógica de negocio dentro de cada flujo generado.
Este orden evita el problema clásico de «implementé la API y luego el consumidor me pidió cambiar la forma del JSON» — con API-first ese cambio se detecta en el paso 2, no en producción.
Migrar un proyecto de RAML a OAS
Si tienes proyectos existentes en RAML, no hace falta reescribirlos de golpe:
- MuleSoft mantiene soporte de RAML en runtime — tus APIs en producción siguen funcionando.
- Para proyectos nuevos o refactors grandes, sí conviene migrar a OAS, aprovechando conversores automáticos (existen herramientas open-source y el propio Anypoint Platform ofrece importación).
- No mezcles ambos formatos dentro del mismo proyecto activo — genera confusión en el equipo sobre cuál es la fuente de verdad del contrato.
Si vienes de Cloud IDE y RAML, este cambio va de la mano con la migración a Anypoint Code Builder — lo cubrimos con más detalle en nuestra guía de migración. En el curso de certificación MuleSoft Developer I trabajamos el diseño de API completo con OAS 3.0 desde el primer módulo, exactamente como lo vas a encontrar en el examen y en proyectos reales de 2026 en adelante.