Configurar protocolo SOAP/XML

Configurar protocolo SOAP/XML

Resumen

SOAP/XML es un protocolo para intercambiar información estructurada entre aplicaciones, principalmente servicios web. Además de APIs REST, Vor-Tex permite exponer métodos con protocolo SOAP/XML, lo que facilita modernizar sistemas que necesitan mantener este tipo de servicios sin impactar al resto de los componentes de la organización. Esta guía explica cómo crear y configurar un método SOAP/XML y cómo definir su WSDL.

Antes de comenzar

  • Necesita una API creada y una vista de datos o un pipeline publicados para asociar al método.
  • El protocolo se elige a nivel de método, no de API, igual que REST y WebSocket.

Crear el método

Agregar el método y elegir la vista

Con la API creada o seleccionada, agregue un método y seleccione la vista o el pipeline que lo ejecutará.

Agregar un método en la API Selección de la vista que ejecutará el método

Seleccionar el protocolo SOAP

En las especificaciones del método, seleccione el protocolo SOAP. Los métodos SOAP/XML solo admiten POST como tipo de solicitud.

Selección del protocolo SOAP en el método

Completar los campos SOAP

Al elegir SOAP aparecen estos campos:

  • Versión: por ahora está disponible la 1.1.
  • Method (operación): el nombre del método u operación.
  • Prefijo: opcional.
  • Namespace del método: el espacio de nombres.
Campos específicos del protocolo SOAP

Definir el WSDL

El WSDL (Web Services Description Language) es un XML que describe el servicio web y se usa para verificar las solicitudes al método. Se define para cada método y puede incluir un esquema XSD (XML Schema Definition) con validaciones sobre el contenido XML de la solicitud.

Campo WSDL del método Editor del WSDL con el esquema XSD

Ejemplo

Body de la solicitud que se envía al método:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:fix="http://www.fixprotocol.org/FIXML-5-0">
  <soapenv:Header/>
  <soapenv:Body>
    <fix:Employees>
      <fix:Name Type="public">John</fix:Name>
      <fix:Lastname Type="public">Doe</fix:Lastname>
      <fix:BirthDate Type="private">1986-01-31</fix:BirthDate>
    </fix:Employees>
  </soapenv:Body>
</soapenv:Envelope>

Respuesta esperada en caso exitoso:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:fix="http://www.fixprotocol.org/FIXML-5-0">
  <soapenv:Header/>
  <soapenv:Body>
    <fix:EmployeesResponse>
      <fix:response>CREATED</fix:response>
    </fix:EmployeesResponse>
  </soapenv:Body>
</soapenv:Envelope>

Reglas de validación del cuerpo de la solicitud:

CampoTipoRestriccionesObligatorioValor fijo en atributo Type
NamestringMáx. 120 caracteresSípublic
LastnamestringMáx. 120 caracteresSípublic
BirthDatedateFormato YYYY-MM-DDNoprivate

WSDL con el XSD embebido que aplica esas reglas:

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="EmployeesService" targetNamespace="http://www.fixprotocol.org/FIXML-5-0" xmlns:tns="http://www.fixprotocol.org/FIXML-5-0" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
  <wsdl:types>
    <xs:schema targetNamespace="http://www.fixprotocol.org/FIXML-5-0" xmlns="http://www.fixprotocol.org/FIXML-5-0" elementFormDefault="qualified">
      <xs:element name="Employees">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="Name">
              <xs:complexType>
                <xs:simpleContent>
                  <xs:extension base="nameType">
                    <xs:attribute name="Type" use="required" fixed="public"/>
                  </xs:extension>
                </xs:simpleContent>
              </xs:complexType>
            </xs:element>
            <xs:element name="Lastname">
              <xs:complexType>
                <xs:simpleContent>
                  <xs:extension base="lastnameType">
                    <xs:attribute name="Type" use="required" fixed="public"/>
                  </xs:extension>
                </xs:simpleContent>
              </xs:complexType>
            </xs:element>
            <xs:element name="BirthDate" minOccurs="0">
              <xs:complexType>
                <xs:simpleContent>
                  <xs:extension base="birthdateType">
                    <xs:attribute name="Type" use="required" fixed="private"/>
                  </xs:extension>
                </xs:simpleContent>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:simpleType name="nameType">
        <xs:restriction base="xs:string">
          <xs:maxLength value="120"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType name="lastnameType">
        <xs:restriction base="xs:string">
          <xs:maxLength value="120"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType name="birthdateType">
        <xs:restriction base="xs:date"/>
      </xs:simpleType>
      <xs:element name="EmployeesResponse">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="response" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>
  </wsdl:types>
  <wsdl:message name="EmployeesRequest">
    <wsdl:part name="parameters" element="tns:Employees"/>
  </wsdl:message>
  <wsdl:message name="EmployeesResponseMessage">
    <wsdl:part name="parameters" element="tns:EmployeesResponse"/>
  </wsdl:message>
  <wsdl:portType name="EmployeesPortType">
    <wsdl:operation name="CreateEmployee">
      <wsdl:input message="tns:EmployeesRequest"/>
      <wsdl:output message="tns:EmployeesResponseMessage"/>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="EmployeesBinding" type="tns:EmployeesPortType">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="CreateEmployee">
      <soap:operation soapAction="http://www.fixprotocol.org/FIXML-5-0/CreateEmployee"/>
      <wsdl:input>
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="EmployeesService">
    <wsdl:port name="EmployeesPort" binding="tns:EmployeesBinding">
      <soap:address location="http://localhost:8080/employees"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

Resultado esperado

El método queda expuesto como SOAP/XML bajo los estándares de ese tipo de servicios: acepta solicitudes POST con el sobre SOAP y valida su contenido contra el WSDL definido.

Errores frecuentes

  • No se puede elegir otro tipo de solicitud que POST: es el comportamiento esperado; los métodos SOAP/XML solo admiten POST.
  • La solicitud es rechazada por validación: el contenido no cumple el XSD del WSDL, por ejemplo un campo supera el máximo de caracteres o falta un atributo Type obligatorio.

Artículos relacionados