SOAP frente a REST

La comparación que siempre cae: protocolo contra estilo, contrato obligatorio contra documentación, y en qué escenario conviene cada uno, con las APIs de Java de cada familia.

Protocolo frente a estilo arquitectónico

La diferencia de fondo no está en la sintaxis, está en la categoría. SOAP es un protocolo: una especificación que dice exactamente cómo tiene que ser el mensaje, qué elementos lleva y cómo se señalan los errores. Cumplirlo o no es una cuestión objetiva, y hay validadores que lo comprueban.

REST es un estilo arquitectónico: un conjunto de restricciones de diseño sobre cómo organizar un sistema distribuido. No dice qué formato tiene el mensaje ni qué campos lleva; dice que hay recursos, que se identifican con URI, que el interfaz es uniforme y que el servidor no guarda sesión. Sobre esa base, cada API decide su propio formato.

Un mensaje se comprueba contra SOAP; un diseño se juzga contra REST. Confundir esas dos categorías es el error clásico de este apartado.

Para el examen

SOAP: un protocolo: se cumple o no, y se puede validar
REST: un estilo arquitectónico: se juzga un diseño
Conclusión: no son dos protocolos rivales

La comparación punto por punto

Aspecto	SOAP	REST
Qué es	Un protocolo estandarizado por la W3C	Un estilo de arquitectura, sin organismo que lo norme
Formato del mensaje	XML obligatorio, dentro de un sobre	Libre: en la práctica JSON, aunque admite XML u otros
Contrato	WSDL, formal y generado por el motor	No hay contrato obligatorio; se documenta aparte
Transporte	Independiente: HTTP, correo, colas de mensajes	HTTP, que forma parte del estilo
Uso de HTTP	Solo como transporte, siempre con POST	Como interfaz: los verbos y los códigos de estado significan algo
Puntos de acceso	Uno solo para todas las operaciones	Uno por recurso
Errores	Elemento Fault dentro del sobre	Códigos de estado HTTP
Seguridad	WS-Security a nivel de mensaje, además de TLS	TLS en el canal, más testigos como OAuth 2.0 o JWT
Peso y verbosidad	Alto: el XML y el sobre añaden mucho texto	Bajo: JSON es más compacto

Una fila merece un comentario aparte: el uso de HTTP. SOAP lo trata como un camión, un mero medio para llevar el sobre de un sitio a otro, y por eso siempre usa POST y le da igual el código de estado salvo para distinguir 200 de 500. REST lo trata como el propio idioma: el verbo dice qué se hace y el código de estado dice qué ha pasado.

Para el examen

Formato: XML obligatorio en SOAP; libre, normalmente JSON, en REST
Contrato: WSDL obligatorio frente a ninguno obligatorio
Puntos de acceso: uno solo frente a uno por recurso
Errores: Fault frente a código de estado HTTP
Seguridad: WS-Security frente a TLS más OAuth o JWT

El contrato: WSDL frente a la documentación de las APIs

En SOAP el contrato es parte del servicio: el WSDL se genera solo, es obligatorio en la práctica y una herramienta puede leerlo y fabricar el código del cliente sin intervención humana. Eso da rigidez, que en integraciones entre organizaciones es una ventaja: lo que no está en el contrato, no existe.

En REST no hay contrato obligatorio, así que la descripción de la API se hace con formatos externos. Los que aparecen en el temario son cuatro.

Formato	Nota
WADL	El intento temprano de hacer un WSDL para servicios REST, en XML. Tuvo poco recorrido
WSDL 2.0	Puede describir servicios REST gracias a su vinculación HTTP, pero apenas se usó para eso
RAML	Lenguaje de modelado de APIs REST, orientado a diseñar primero y programar después
Swagger, hoy OpenAPI	El estándar de facto actual para describir una API REST

La diferencia no es que REST no se pueda documentar: es que en SOAP el contrato es obligatorio y viene con el servicio, mientras que en REST es una decisión del equipo y se escribe aparte.

Para el examen

En SOAP: el contrato es obligatorio y lo genera el motor
En REST: se documenta aparte
Opciones: WADL, WSDL 2.0, RAML y Swagger
El estándar de facto: Swagger, hoy OpenAPI

Cuándo conviene cada uno

REST domina hoy porque el escenario mayoritario le favorece: APIs públicas, clientes de navegador y de móvil, equipos que iteran deprisa y necesitan algo ligero de consumir. La misma API sirve para cualquier consumidor sin generar código específico para cada uno.

SOAP encaja mejor cuando el contrato formal es un requisito, típicamente en integraciones entre organizaciones o entre administraciones.
SOAP encaja mejor cuando hace falta seguridad a nivel de mensaje que sobreviva a intermediarios, o transacciones distribuidas y mensajería fiable de la familia WS-*.
SOAP encaja mejor cuando el transporte no va a ser HTTP, por ejemplo sobre una cola de mensajes.
REST encaja mejor en APIs abiertas, en aplicaciones web y móviles, y cuando importan la sencillez, el peso del mensaje y la posibilidad de aprovechar la caché de HTTP.

No es una competición con ganador: en un mismo organismo conviven servicios SOAP heredados de integraciones antiguas y APIs REST nuevas para los canales digitales. Lo que se pregunta en el examen es saber justificar la elección, no repetir que uno es mejor.

Para el examen

Dónde domina REST: APIs públicas, móviles y equipos que iteran rápido
Dónde sigue SOAP: integraciones entre organizaciones
Qué necesitan esas integraciones: contrato formal, seguridad a nivel de mensaje y transacciones

JAX-RS: REST en Java

Cada familia tiene su API en Java, y conviene no confundirlas. Para SOAP es JAX-WS, ya visto; para REST es JAX-RS, que es la que se usa cuando lo que se quiere publicar es un recurso y no una operación.

Sus implementaciones más conocidas son Jersey, RESTEasy, Apache CXF y Restlet. Varias de ellas no hay ni que instalarlas por separado, porque los servidores de aplicaciones del mercado ya las traen incorporadas de serie.

JAX-WS y JAX-RS se parecen en el nombre y en la forma de trabajar (una clase Java corriente más anotaciones), pero publican cosas distintas: JAX-WS un servicio SOAP y JAX-RS un recurso REST.

Para el examen

JAX-WS: publica servicios SOAP
JAX-RS: publica recursos REST
En qué se parecen: en el nombre y en trabajar con clase más anotaciones

Las anotaciones de JAX-RS

El trabajo en JAX-RS se hace declarando: se toma una clase Java corriente y, a base de anotaciones, se convierte en un recurso web con sus rutas, sus verbos y sus formatos. Las anotaciones se agrupan en cuatro familias.

Grupo	Anotaciones	Para qué
Rutas y métodos	@Path, @GET, @POST, @PUT, @DELETE, @HEAD	Fijar la ruta de acceso de la clase o del método y el verbo HTTP al que responde
Formatos	@Produces, @Consumes	Declarar los tipos de medios MIME que devuelve y los que acepta
Datos de la petición	@PathParam, @QueryParam, @MatrixParam, @HeaderParam, @CookieParam, @FormParam	Extraer un valor de la ruta, de la cadena de consulta, de la matriz, de una cabecera, de una cookie o de un formulario
Apoyo	@DefaultValue, @Context	Dar un valor por defecto cuando el parámetro no llega, y obtener el contexto de ejecución

java

@Path("/alumnos/{alumno}/intentos")
public class IntentosResource {

  @GET
  @Produces("application/json")
  public List<Intento> listar(
      @PathParam("alumno") long alumnoId,
      @QueryParam("tema") @DefaultValue("todos") String tema) {
    // devuelve los intentos del alumno, filtrados por tema
  }

  @POST
  @Consumes("application/json")
  public Response registrar(Intento intento) {
    // crea el intento y responde con 201
  }
}

Regla para no equivocarse: @Path, @GET y @QueryParam son de JAX-RS (REST); @WebService, @WebMethod y @WebParam son de JAX-WS (SOAP).

Para el examen

De JAX-RS (REST): Path, GET y QueryParam
De JAX-WS (SOAP): WebService, WebMethod y WebParam
Por qué importa: es la confusión que más se pregunta