Paradigmas de API

REST es un estilo de arquitectura, no un protocolo: lo describió Roy Fielding en su tesis doctoral en el año 2000. Cada cosa que expone la API es un recurso con su URL (/usuarios/7, /usuarios/7/posts), y los verbos de HTTP dicen qué hacer con él: GET para leer, POST para crear, PUT o PATCH para modificar y DELETE para borrar. Los códigos de estado cuentan el resultado: 201 Created, 404 Not Found, 409 Conflict.

Es sin estado (stateless): cada petición lleva todo lo necesario para atenderla, incluido el token de autenticación, y el servidor no recuerda nada de las anteriores. Eso permite repartir las peticiones entre muchos servidores y aprovechar la caché de HTTP, porque un GET a la misma URL debería devolver lo mismo.

La versión más estricta añade HATEOAS: cada respuesta incluye enlaces a las acciones posibles, como en una página web, para que el cliente navegue la API sin conocer las URLs de antemano. Pocas APIs reales lo aplican del todo.

Cada API REST decide a su manera dónde van los datos, cómo se pagina o cómo se piden los recursos relacionados. JSON:API es una especificación que lo deja todo acordado: cada recurso va en data con su type y su id, sus campos en attributes y sus vínculos con otros recursos en relationships.

Dos parámetros resuelven buena parte del over- y el under-fetching sin salir de REST: include incrusta los recursos relacionados en la misma respuesta, dentro de included, y los sparse fieldsets (fields[tipo]=campo1,campo2) limitan los campos que vuelven. También define cómo ordenar (sort), paginar (page) y devolver errores.

GraphQL nació en Facebook y se publicó en 2015; hoy lo mantiene la GraphQL Foundation. La API se describe con un esquema de tipos (lo verás en la lección «GraphQL SDL» del módulo de lenguajes) y se expone en una única URL, normalmente /graphql. El cliente envía una consulta que enumera los campos que necesita, y la respuesta tiene exactamente esa forma.

Así desaparecen el over-fetching, porque no llega ningún campo que no hayas pedido, y el under-fetching, porque en una sola consulta puedes atravesar relaciones: el usuario, sus posts y los comentarios de cada post. Las escrituras se hacen con mutaciones y el tiempo real con suscripciones, que verás en la próxima lección.

En el servidor, cada campo lo resuelve una función (un resolver). Si pides 20 posts con su autor y cada resolver de autor consulta la base de datos por separado, haces 1 + 20 consultas: el problema N+1. La solución habitual es agrupar esas búsquedas en una sola, con herramientas como DataLoader.

XML-RPC apareció en 1998 con una idea sencilla: enviar por POST un documento XML <methodCall> con el nombre del método y sus parámetros, y recibir un <methodResponse> con el resultado o un <fault> con el error. Solo tiene unos pocos tipos: enteros, textos, booleanos, decimales, fechas, binario en base64, estructuras y listas.

Es el antecesor directo de SOAP, que lo amplió con todo lo que le faltaba. Hoy apenas se usa en proyectos nuevos, pero sigue vivo en sistemas veteranos: WordPress, por ejemplo, todavía expone un xmlrpc.php.

En SOAP, cada mensaje es un documento XML con un sobre (Envelope) que contiene una cabecera opcional (Header) y un cuerpo (Body) con la operación y sus datos. Los errores llegan como un Fault. Es un estándar del W3C y casi siempre viaja por HTTP, aunque admite otros transportes.

Su pieza central es el WSDL, un documento XML que describe las operaciones, los tipos de datos (con esquemas XSD) y la dirección del servicio. A partir de él, las herramientas generan el código cliente. Alrededor creció la familia de estándares WS-*: WS-Security, por ejemplo, firma y cifra partes del mensaje dentro del propio XML, de modo que la protección no depende solo de HTTPS y sobrevive a los intermediarios.

JSON-RPC 2.0 es una especificación diminuta. Una petición es un objeto con jsonrpc: "2.0", el method, sus params y un id; la respuesta trae el mismo id y un result o un error con código y mensaje. No le importa el transporte: funciona sobre HTTP, WebSocket o la entrada y salida estándar de un proceso.

Una petición sin id es una notificación: el servidor la ejecuta, pero no responde. Y puedes enviar un lote (batch): un array de peticiones que vuelve como un array de respuestas, que relacionas por su id porque pueden llegar en cualquier orden.

Su sencillez explica dónde aparece: los nodos de Ethereum, el Language Server Protocol con el que tu editor habla con los analizadores de código y el Model Context Protocol (MCP) de los asistentes de IA usan JSON-RPC.

gRPC lo creó Google y lo publicó como código abierto en 2015. Los servicios y sus mensajes se definen en un archivo .proto con Protocol Buffers, y un compilador genera el cliente y el servidor en muchos lenguajes: llamas a cliente.ObtenerPost({ id: 42 }) como a cualquier función. Los mensajes viajan en un formato binario compacto, mucho más pequeño y rápido de procesar que el JSON equivalente.

Funciona sobre HTTP/2, que permite muchas llamadas a la vez por una misma conexión y streaming: además de la llamada simple, el servidor puede enviar una serie de respuestas, el cliente una serie de peticiones, o ambos a la vez.

Los navegadores no dejan a JavaScript controlar HTTP/2 al nivel que gRPC necesita, así que una web no puede llamar directamente a un servicio gRPC. Para eso existe gRPC-Web: el navegador usa una variante compatible y un proxy, como Envoy, la traduce.