¿Cuál es la diferencia entre OpenAPI y WSDL? #

OpenAPI y WSDL (Web Services Description Language) son lenguajes de descripción de interfaces: describen las operaciones, las entradas, las salidas y los tipos de datos de una API en un formato legible por máquinas. A pesar de este propósito compartido, difieren de manera fundamental en los protocolos que describen, los estilos arquitectónicos que admiten, los formatos que utilizan y el ecosistema de herramientas construido a su alrededor. Comprender estas diferencias ayuda a los equipos a decidir con criterio qué estándar se ajusta a su situación.

Contexto histórico #

WSDL surgió a principios de la década de 2000 como parte del ecosistema de servicios web SOAP (Simple Object Access Protocol). El W3C estandarizó WSDL 1.1 en 2001 y WSDL 2.0 llegó en 2007. Durante los años 2000, SOAP y WSDL dominaron la integración empresarial, en particular en los sistemas de servicios financieros, sanidad y administraciones públicas.

OpenAPI (originalmente Swagger) surgió en 2011 para describir API REST, que habían crecido con rapidez como alternativa a SOAP. Swagger fue donado a la Linux Foundation en 2016 y se convirtió en la especificación OpenAPI bajo la OpenAPI Initiative. OpenAPI 3.0 se publicó en 2017; OpenAPI 3.1 (alineada con JSON Schema) llegó en 2021.

Los dos estándares reflejan dos épocas distintas del desarrollo de API y dos filosofías arquitectónicas diferentes.

Protocolo y estilo arquitectónico #

Esta es la diferencia más fundamental:

WSDL describe los servicios en términos de operaciones (llamadas a procedimientos remotos con entradas y salidas tipadas), vinculaciones (bindings) (cómo se transmiten las operaciones, por ejemplo, SOAP sobre HTTP), puertos (ports) (las direcciones de los endpoints) y mensajes (las estructuras de datos). Este modelo RPC se corresponde directamente con el enfoque de SOAP, centrado en las operaciones.

OpenAPI describe las API en términos de rutas (recursos identificados por URL), operaciones (métodos HTTP sobre esos recursos), parámetros (de ruta, de consulta, de encabezado y de cookie), cuerpos de solicitud y respuestas. Este modelo orientado a recursos se corresponde con la forma en que REST representa el estado mediante URL y verbos HTTP estándar.

Formato del documento #

Los documentos WSDL son XML. Un documento WSDL mínimo es extenso y requiere familiaridad con los espacios de nombres XML, los tipos de esquema, las definiciones de mensajes, los tipos de puerto, las vinculaciones y los servicios:

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
                  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:xs="http://www.w3.org/2001/XMLSchema"
                  xmlns:tns="http://example.com/users"
                  targetNamespace="http://example.com/users">

  <wsdl:types>
    <xs:schema targetNamespace="http://example.com/users">
      <xs:element name="GetUserRequest">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="userId" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="GetUserResponse">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="id" type="xs:string"/>
            <xs:element name="email" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>
  </wsdl:types>

  <wsdl:message name="GetUserInput">
    <wsdl:part name="parameters" element="tns:GetUserRequest"/>
  </wsdl:message>
  <wsdl:message name="GetUserOutput">
    <wsdl:part name="parameters" element="tns:GetUserResponse"/>
  </wsdl:message>

  <wsdl:portType name="UserServicePortType">
    <wsdl:operation name="GetUser">
      <wsdl:input message="tns:GetUserInput"/>
      <wsdl:output message="tns:GetUserOutput"/>
    </wsdl:operation>
  </wsdl:portType>

  <wsdl:binding name="UserServiceSoapBinding" type="tns:UserServicePortType">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="GetUser">
      <soap:operation soapAction="GetUser"/>
      <wsdl:input><soap:body use="literal"/></wsdl:input>
      <wsdl:output><soap:body use="literal"/></wsdl:output>
    </wsdl:operation>
  </wsdl:binding>

  <wsdl:service name="UserService">
    <wsdl:port name="UserServicePort" binding="tns:UserServiceSoapBinding">
      <soap:address location="https://api.example.com/users"/>
    </wsdl:port>
  </wsdl:service>

</wsdl:definitions>

Los documentos OpenAPI son YAML o JSON. La misma operación se expresa de forma mucho más concisa:

openapi: 3.1.0
info:
  title: User API
  version: 1.0.0
paths:
  /users/{userId}:
    get:
      summary: Get a user
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The user
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  email:
                    type: string

La versión de OpenAPI es bastante más legible y requiere menos maquinaria de espacios de nombres y esquemas XML.

Lenguajes de esquema #

WSDL utiliza XML Schema Definition (XSD) para definir los tipos de datos. XSD es un lenguaje de esquemas potente pero complejo, diseñado específicamente para documentos XML.

OpenAPI utiliza JSON Schema (adoptado por completo en OpenAPI 3.1) para definir los tipos de datos. JSON Schema es ampliamente conocido, cuenta con un rico ecosistema de herramientas y resulta más accesible para los desarrolladores familiarizados con JSON.

Ecosistema de herramientas #

Ambos estándares cuentan con ecosistemas de herramientas, pero difieren de forma notable en escala y modernidad:

El ecosistema de OpenAPI es sustancialmente mayor, está mantenido de forma más activa y se integra mejor con los flujos de trabajo de desarrollo modernos.

Relevancia actual #

WSDL y SOAP siguen siendo relevantes en:

• Sistemas empresariales heredados: muchos grandes sistemas financieros, sanitarios y gubernamentales creados en los años 2000 utilizan API SOAP que no se han sustituido
• Aplicación estricta de contratos: los estándares integrados de SOAP, como WS-Security, WS-ReliableMessaging y WS-AtomicTransaction, ofrecen funciones que REST con OpenAPI no cubre de forma nativa
• Interoperabilidad con sistemas más antiguos: algunos middleware empresariales requieren SOAP

OpenAPI es el estándar dominante en:

• Desarrollo de nuevas API REST: prácticamente todas las nuevas API HTTP se documentan con OpenAPI
• API de cara al público: las herramientas, la documentación y la generación de SDK de OpenAPI lo convierten en el estándar para las API públicas
• Microservicios: las API REST/HTTP ligeras de las arquitecturas de microservicios utilizan OpenAPI

Conclusión #

OpenAPI y WSDL abordan el mismo problema fundamental, describir la interfaz de un servicio de forma legible por máquinas, pero para ecosistemas de protocolos totalmente distintos. WSDL se diseñó para el mundo de SOAP, centrado en las operaciones y basado en XML; OpenAPI se diseñó para el mundo de REST, centrado en los recursos y basado en JSON. Para los equipos que crean hoy nuevas API HTTP, OpenAPI es la opción por defecto. WSDL sigue siendo importante para mantener servicios SOAP heredados, creados durante la era de los servicios web empresariales, o integrarse con ellos.

Última actualización: 30 de abril de 2026.