Si alguna vez has intentado llamar a un servicio gRPC desde un navegador, ya conoces la fricción. Los navegadores no pueden hablar gRPC en su estado puro porque no pueden controlar los tráileres HTTP, por lo que terminas añadiendo un proxy como Envoy solo para traducir el tráfico. ConnectRPC elimina ese paso. Te permite construir APIs basadas en Protobuf que un navegador puede llamar directamente, que responden a un comando curl simple, y que aún interoperan con el ecosistema gRPC más amplio.
Esta guía explica qué es ConnectRPC, el problema que resuelve el protocolo Connect, cómo se compara Connect con gRPC, gRPC-Web y REST, y cómo se ve una solicitud Connect a través de HTTP. También verás cómo probar y depurar endpoints de Connect y gRPC con un cliente de API estándar.
Qué es ConnectRPC
ConnectRPC es una familia de bibliotecas para construir APIs HTTP compatibles con navegadores y gRPC a partir de Protocol Buffers. Defines tu servicio en un archivo .proto, generas código e implementas tus manejadores. Connect se encarga del enrutamiento, serialización, compresión y generación de clientes.
El proyecto fue creado por Buf, la empresa detrás de las herramientas de compilación buf para Protobuf, y ahora es un proyecto sandbox de la Cloud Native Computing Foundation (CNCF). Este linaje es importante: Connect está diseñado para encajar en el mismo flujo de trabajo centrado en el esquema que los equipos ya utilizan con buf y Protobuf.
Un servidor ConnectRPC soporta tres protocolos a la vez:
- gRPC: compatibilidad total, incluyendo streaming y tráileres.
- gRPC-Web: soporte directo, sin necesidad de un proxy separado.
- Connect: su propio protocolo basado en HTTP, optimizado para la web.
Dado que un solo servidor habla los tres, un cliente gRPC puede llamar a un servidor Connect, y un cliente Connect puede llamar a cualquier servidor gRPC. Eliges el protocolo por cliente, a menudo con un solo cambio de configuración y sin reescritura de código.
El Problema que Resuelve Connect
gRPC es rápido y fuertemente tipado, pero hace suposiciones que la web no respeta. Se basa en HTTP/2 y en los tráileres HTTP para llevar información de estado. Los navegadores no exponen los tráileres a JavaScript, por lo que un navegador no puede actuar como un cliente gRPC nativo. La solución habitual es gRPC-Web más un proxy de traducción como Envoy que se sitúa entre el navegador y tu backend gRPC.
Eso funciona, pero añade componentes en movimiento. Ahora ejecutas y configuras un proxy, y depuras un salto adicional. Para los equipos que desean APIs tipadas y acceso desde el navegador sin esa sobrecarga, la configuración se siente más pesada de lo que debería.
Connect toma una ruta diferente. Su propio protocolo se ejecuta sobre HTTP estándar, por lo que un navegador puede llamarlo directamente y no necesitas un proxy para el tráfico del navegador. Si también necesitas servir a clientes gRPC existentes, el mismo servidor Connect también los maneja. Obtienes un backend que responde por igual a navegadores, herramientas de línea de comandos y servicios gRPC.
Connect vs gRPC vs gRPC-Web vs REST
Estos cuatro enfoques se superponen, por lo que ayuda a compararlos.
gRPC utiliza Protobuf sobre HTTP/2 con enmarcado binario y tráileres. Es eficiente y soporta los cuatro modos de streaming, pero es incómodo de llamar desde un navegador o con un shell. Si deseas un repaso sobre la capa de transporte, consulta cómo funcionan juntos gRPC y HTTP/2.
gRPC-Web es una variante de gRPC amigable para navegadores. Todavía se centra en Protobuf y usualmente necesita un proxy para conectar con un backend gRPC real. Nuestra guía sobre qué es gRPC-Web cubre dónde encaja.
Connect mantiene el esquema de Protobuf y el modelo de método estilo gRPC, pero su protocolo se ejecuta limpiamente sobre HTTP/1.1, HTTP/2 y HTTP/3. Las llamadas unarias llevan un cuerpo JSON o Protobuf simple sin enmarcado binario gRPC, y las respuestas usan códigos de estado HTTP reales. Esa combinación es lo que hace que una llamada Connect sea tan accesible como cualquier llamada REST.
REST está orientado a recursos y el esquema es opcional. Es el estilo más universalmente soportado, pero carece de la generación de código y el tipado estricto que Protobuf te ofrece. Si estás sopesando las ventajas y desventajas, gRPC vs REST desglosa las diferencias.
La versión corta: Connect tiene como objetivo brindarte el tipado y las herramientas de gRPC con el alcance y la capacidad de depuración de REST. Se apoya en Protobuf y el modelo de método de gRPC mientras elimina las partes que los navegadores y los shells no pueden manejar.
Una Solicitud Connect sobre HTTP
Esto es lo que hace que Connect sea accesible. Una llamada unaria de Connect es una solicitud HTTP POST ordinaria. La ruta de la URL proviene directamente de tu esquema Protobuf, y el cuerpo es JSON o Protobuf binario sin enmarcado adicional.
El formato de la ruta es /<package>.<Service>/<Method>. Así, un método Greet en un GreetService en el paquete greet.v1 se encuentra en /greet.v1.GreetService/Greet.
Puedes llamarlo con curl:
curl \
--header "Content-Type: application/json" \
--data '{"name": "Jane"}' \
http://localhost:8080/greet.v1.GreetService/Greet
La respuesta es JSON simple:
{"greeting": "Hello, Jane!"}
Sin cliente personalizado, sin proxy, sin decodificación binaria. Esa es toda la solicitud. Dado que el cuerpo es JSON real y el estado es un código de estado HTTP real, cualquier herramienta que hable HTTP puede inspeccionar la llamada. Esta es la propiedad que separa el protocolo Connect del gRPC puro, donde la misma solicitud estaría envuelta en un enmarcado binario y llevaría su estado en un tráiler.
Connect soporta dos tipos de contenido para solicitudes unarias:
application/jsonpara payloads JSON legibles por humanos.application/protopara Protobuf binario compacto.
Envías Protobuf binario cuando deseas un tamaño de cable más pequeño y JSON cuando deseas legibilidad durante el desarrollo. Para enviar binario, cambia la cabecera y pasa un cuerpo codificado:
curl \
--header "Content-Type: application/proto" \
--data-binary @request.bin \
http://localhost:8080/greet.v1.GreetService/Greet
Las llamadas de streaming utilizan un tipo de contenido diferente (application/connect+proto o application/connect+json) y envuelven cada mensaje en un sobre: un byte de banderas, una longitud big-endian de cuatro bytes, luego el mensaje. Las llamadas unarias omiten ese sobre por completo, por lo que se mapean tan limpiamente a una solicitud HTTP normal. Si estás eligiendo entre formatos de cable para tus payloads, Protobuf vs JSON cubre las ventajas y desventajas de tamaño y legibilidad.
Soporte de Idiomas y Herramientas buf
ConnectRPC ofrece implementaciones en varios lenguajes. Go y TypeScript (tanto para navegador como para Node.js) son estables y están listos para producción. Swift está disponible para plataformas Apple, con Kotlin para JVM y Android, y Python en beta. Esa distribución te permite compartir un contrato Protobuf en un backend Go y un frontend TypeScript sin escribir clientes a mano.
La generación de código se realiza a través de la cadena de herramientas buf. Describes tu servicio en un archivo .proto, luego utilizas plugins de buf para generar mensajes y manejadores Connect. Un proyecto Go usa dos plugins: protoc-gen-go para los mensajes Protobuf y protoc-gen-connect-go para los manejadores y clientes Connect.
Los plugins se listan en un archivo buf.gen.yaml, y ejecutas la generación con un comando:
buf generate
Eso produce estructuras de mensajes tipadas más el código de servidor y cliente para tu servicio. A partir de ahí, implementas los métodos manejadores y los registras en un servidor HTTP. Debido a que el código generado apunta a la biblioteca estándar net/http en Go, no necesitas un runtime de servidor separado; un manejador Connect es un manejador HTTP normal que puedes montar junto a tus rutas existentes.
Pruebas y Depuración de Endpoints Connect y gRPC
Dado que las llamadas unarias de Connect son HTTP simple con un cuerpo JSON, puedes probarlas de la misma manera que pruebas cualquier endpoint REST. Esa es una ventaja práctica: no se requiere un cliente especial para interactuar con tu servicio durante el desarrollo.
En Apidog, envías una solicitud unaria Connect como una solicitud HTTP. Establece el método en POST, usa la URL derivada del esquema como http://localhost:8080/greet.v1.GreetService/Greet, añade la cabecera Content-Type: application/json y coloca tu mensaje en el cuerpo JSON:
{"name": "Jane"}
Obtienes la respuesta JSON y un código de estado HTTP real, sobre los cuales puedes afirmar directamente. Apidog no es un cliente Connect dedicado, pero no necesita serlo; estás ejerciendo la superficie HTTP que expone el protocolo Connect, exactamente como lo hace curl, con una interfaz de usuario, solicitudes guardadas e historial. Para una introducción rápida a los verbos involucrados, consulta qué son los métodos HTTP.
Debido a que un servidor Connect también habla gRPC, el lado gRPC de tu servicio también es testeable. Apidog soporta endpoints gRPC, por lo que puedes importar el mismo archivo .proto, navegar por los métodos del servicio y llamarlos con una solicitud tipada. Eso significa que una herramienta cubre ambas caras del servidor: el protocolo Connect amigable con HTTP y el protocolo gRPC nativo. Si gRPC es tu principal preocupación, cómo probar APIs gRPC de manera eficiente describe el flujo de trabajo.
Una vez que tus solicitudes se comportan correctamente, puedes moverlas a comprobaciones automatizadas. Guarda tus llamadas Connect y gRPC como escenarios de prueba, luego ejecútalas en CI con la CLI de Apidog. Instálala con Node:
npm install -g apidog-cli
Luego ejecuta un escenario o suite guardado, apuntando a un entorno y eligiendo formatos de informe:
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t <scenarioOrSuiteId> \
-e <environmentId> \
-r cli,html,junit
La CLI no tiene interfaz gráfica (headless), por lo que se integra en cualquier paso de CI que pueda ejecutar Node. Ejecuta escenarios y suites de prueba guardados en lugar de enviar solicitudes ad hoc, lo que la hace adecuada para comprobaciones de regresión en tus endpoints Connect y gRPC. Para una descripción completa, consulta el tutorial de la CLI de Apidog para probar una API desde la línea de comandos.
Preguntas Frecuentes
¿Es ConnectRPC lo mismo que gRPC? No. ConnectRPC es un framework que implementa tres protocolos: gRPC, gRPC-Web y su propio protocolo Connect. Un servidor Connect interopera con clientes y servidores gRPC, por lo que encaja en el ecosistema gRPC, pero el protocolo Connect en sí mismo es un diseño separado basado en HTTP que los navegadores y shells pueden llamar directamente.
¿Todavía necesito un proxy como Envoy para llegar a un navegador? No para el protocolo Connect. Connect se ejecuta sobre HTTP estándar, por lo que un navegador puede llamar a un servidor Connect sin un proxy de traducción. Solo recurrirías a un proxy como Envoy cuando necesites puentear el tráfico del navegador a un backend que solo hable gRPC nativo y nada más.
¿Qué lenguajes soporta ConnectRPC? Go y TypeScript (navegador y Node.js) son las implementaciones estables y listas para producción. Swift, Kotlin y Python también están disponibles, con Python en fase beta. Todos ellos se generan a partir del mismo esquema Protobuf.
¿Cuál es la relación entre Connect y buf? ConnectRPC fue creado por Buf y utiliza la cadena de herramientas buf para la generación de código. Ejecutas buf generate con plugins como protoc-gen-connect-go para producir manejadores y clientes a partir de tus archivos .proto.
¿Puedo probar un endpoint Connect con un cliente de API normal? Sí. Las llamadas unarias de Connect son solicitudes HTTP POST con un cuerpo JSON o Protobuf y un código de estado HTTP real. Cualquier cliente HTTP, incluidos curl y Apidog, puede enviar una. Apidog también puede llamar al lado gRPC del mismo servidor importando el archivo .proto.