Si eres un desarrollador que trabaja con APIs, probablemente sepas lo importante que es probarlas y depurarlas antes de implementarlas en producción. Quieres asegurarte de que tus APIs sean fiables, seguras y tengan un buen rendimiento, y que cumplan con las expectativas de tus clientes y usuarios.
Pero, ¿cómo pruebas y depuras tus APIs, especialmente si utilizan gRPC, un protocolo moderno y eficiente para la comunicación entre microservicios? Ahí es donde entra grpc-curl. grpc-curl es una herramienta de línea de comandos que te permite interactuar con los servidores gRPC de forma sencilla e intuitiva.
En esta entrada del blog, te mostraré cómo usar grpc-curl para probar y depurar tus APIs, y por qué deberías considerar usarlo para tus proyectos gRPC.
¿Qué es grpc-curl?
grpc-curl es una herramienta de línea de comandos que te permite invocar métodos RPC en un servidor gRPC desde la línea de comandos. Soporta varios métodos RPC, incluyendo unario, transmisión del servidor, transmisión del cliente y transmisión bidireccional. También puedes explorar el esquema de los servicios gRPC, ya sea consultando un servidor que soporte la reflexión del servidor o cargando archivos protoset compilados.
grpc-curl está escrito en .NET, y tiene algunas ventajas sobre gRPCurl, tales como:
- Soporta tanto .NET Core como .NET Framework, y puede ejecutarse en Windows, Linux y Mac OS.
- Tiene una sintaxis más concisa y expresiva, y puede inferir los nombres de los servicios y métodos de la URL.
- Puede formatear automáticamente la salida JSON con colores y sangría, y también puede generar XML o texto plano.
- Puede manejar mejor los mensajes anidados y los campos repetidos, y también puede aceptar entradas de archivos o de la entrada estándar.
- Puede utilizar variables de entorno para opciones comunes, como la URL del servidor, las cabeceras y la configuración de TLS.
- Puede generar fragmentos de código para C#, Java, Python y Go, para ayudarte a escribir tu propio código de cliente.
grpc-curl está disponible como un paquete NuGet, y puedes instalarlo con el siguiente comando:
dotnet tool install -g grpc-curl
¿Cómo usar grpc-curl?
Para usar grpc-curl, necesitas tener un servidor gRPC en ejecución, y necesitas conocer su URL y los nombres de los servicios y métodos que quieres llamar. También necesitas tener el esquema de los servicios gRPC, ya sea usando la reflexión del servidor o cargando archivos protoset.
Para este ejemplo, usaré un servidor gRPC simple que implementa un servicio de calculadora, con cuatro métodos: Add, Subtract, Multiply y Divide. El servidor está escrito en C#, y soporta la reflexión del servidor.
Para iniciar el servidor, ejecuta el siguiente comando desde la carpeta del proyecto:
dotnet run
El servidor escuchará en el puerto 5000 por defecto. Puedes cambiar el número de puerto en el archivo appsettings.json.
Para llamar al método Add en el servidor, ejecuta el siguiente comando desde otra terminal:
grpc-curl http://localhost:5000 Calculator/Add -d '{"x": 3, "y": 5}'
La salida debería verse así:
{
"result": 8
}
Como puedes ver, grpc-curl infiere automáticamente los nombres de los servicios y métodos de la URL, y formatea la salida JSON con colores y sangría. También puedes usar la opción -o para especificar un formato de salida diferente, como xml o text.
Para llamar al método Subtract, ejecuta el siguiente comando:
grpc-curl http://localhost:5000 Calculator/Subtract -d '{"x": 10, "y": 4}'
La salida debería verse así:
{
"result": 6
}
Para llamar al método Multiply, ejecuta el siguiente comando:
grpc-curl http://localhost:5000 Calculator/Multiply -d '{"x": 2, "y": 7}'
La salida debería verse así:
{
"result": 14
}
Para llamar al método Divide, ejecuta el siguiente comando:
grpc-curl http://localhost:5000 Calculator/Divide -d '{"x": 15, "y": 3}'
La salida debería verse así:
{
"result": 5
}
Si intentas dividir por cero, obtendrás un mensaje de error, como este:
grpc-curl http://localhost:5000 Calculator/Divide -d '{"x": 15, "y": 0}'
{
"error": "Cannot divide by zero."
}
grpc-curl también soporta métodos de transmisión, que pueden enviar o recibir múltiples mensajes en una sola llamada. Por ejemplo, digamos que tenemos un método de transmisión del servidor llamado Fibonacci, que toma un número n como entrada y devuelve los primeros n números de Fibonacci como un flujo de mensajes. El código del servidor para este método se ve así:
public override async Task Fibonacci(Number request, IServerStreamWriter<Number> responseStream, ServerCallContext context)
{
int n = request.Value;
int a = 0;
int b = 1;
for (int i = 0; i < n; i++)
{
await responseStream.WriteAsync(new Number { Value = a });
int temp = a;
a = b;
b = temp + b;
}
}
Para llamar a este método con grpc-curl, ejecuta el siguiente comando:
grpc-curl http://localhost:5000 Calculator/Fibonacci -d '{"value": 10}'
La salida debería verse así:
{
"value": 0
}
{
"value": 1
}
{
"value": 1
}
{
"value": 2
}
{
"value": 3
}
{
"value": 5
}
{
"value": 8
}
{
"value": 13
}
{
"value": 21
}
{
"value": 34
}
Como puedes ver, grpc-curl imprime cada mensaje a medida que lo recibe del servidor, y cierra la conexión cuando el flujo está completo.
grpc-curl también soporta métodos de transmisión del cliente, que pueden enviar múltiples mensajes al servidor y recibir una sola respuesta. Por ejemplo, digamos que tenemos un método de transmisión del cliente llamado Sum, que toma un flujo de números como entrada y devuelve su suma como respuesta. El código del servidor para este método se ve así:
public override async Task<Number> Sum(IAsyncStreamReader<Number> requestStream, ServerCallContext context)
{
int sum = 0;
await foreach (var number in requestStream.ReadAllAsync())
{
sum += number.Value;
}
return new Number { Value = sum };
}
Para llamar a este método con grpc-curl, necesitamos proporcionar los mensajes de entrada desde un archivo o desde la entrada estándar. Por ejemplo, podemos crear un archivo llamado numbers.json con el siguiente contenido:
{"value": 1}
{"value": 2}
{"value": 3}
{"value": 4}
{"value": 5}
Entonces, podemos ejecutar el siguiente comando:
grpc-curl http://localhost:5000 Calculator/Sum -d @numbers.json
La salida debería verse así:
{
"value": 15
}
Alternativamente, podemos usar el símbolo - para indicar que los mensajes de entrada provienen de la entrada estándar, y luego escribir o pegar los mensajes en la terminal, seguido de Ctrl+D para finalizar la entrada. Por ejemplo:
grpc-curl http://localhost:5000 Calculator/Sum -d -
{"value": 1}
{"value": 2}
{"value": 3}
{"value": 4}
{"value": 5}
^D
La salida debería ser la misma que antes.
grpc-curl también soporta métodos de transmisión bidireccional, que pueden enviar y recibir múltiples mensajes en ambas direcciones. Por ejemplo, digamos que tenemos un método de transmisión bidireccional llamado Chat, que toma un flujo de mensajes como entrada y devuelve un flujo de mensajes como salida. El código del servidor para este método se ve así:
public override async Task Chat(IAsyncStreamReader<Message> requestStream, IServerStreamWriter<Message> responseStream, ServerCallContext context)
{
await foreach (var message in requestStream.ReadAllAsync())
{
Console.WriteLine($"Received: {message.Text}");
var reply = new Message { Text = $"Echo: {message.Text}" };
await responseStream.WriteAsync(reply);
Console.WriteLine($"Sent: {reply.Text}");
}
}
Para llamar a este método con grpc-curl, necesitamos proporcionar los mensajes de entrada desde un archivo o desde la entrada estándar, y necesitamos usar la opción -s para indicar que queremos recibir los mensajes de salida como un flujo. Por ejemplo, podemos crear un archivo llamado chat.json con el siguiente contenido:
{"text": "Hello"}
{"text": "How are you?"}
{"text": "Goodbye"}
Entonces, podemos ejecutar el siguiente comando:
grpc-curl http://localhost:5000 Calculator/Chat -d @chat.json -s
La salida debería verse así:
{
"text": "Echo: Hello"
}
{
"text": "Echo: How are you?"
}
{
"text": "Echo: Goodbye"
}
Como puedes ver, grpc-curl envía cada mensaje al servidor, e imprime cada respuesta del servidor, hasta que el flujo de entrada se agota.
¿Por qué usar grpc-curl?
grpc-curl es una herramienta útil para probar y depurar tus APIs gRPC, porque te permite:
- Invocar cualquier tipo de método RPC, incluyendo métodos de transmisión, desde la línea de comandos, sin escribir ningún código de cliente.
- Explorar el esquema de los servicios gRPC, ya sea consultando un servidor que soporte la reflexión del servidor, o cargando archivos protoset.
- Formatear la salida de diferentes maneras, como JSON, XML o texto plano, con colores y sangría.
- Manejar mensajes anidados y campos repetidos mejor que gRPCurl, y aceptar entradas de archivos o de la entrada estándar.
- Usar variables de entorno para opciones comunes, como la URL del servidor, las cabeceras y la configuración de TLS.
- Generar fragmentos de código para C#, Java, Python y Go, para ayudarte a escribir tu propio código de cliente.
grpc-curl también es fácil de instalar y usar, y funciona en múltiples plataformas, como Windows, Linux y Mac OS. Es compatible tanto con .NET Core como con .NET Framework, y soporta tanto HTTP/1.1 como protocolos HTTP/2.
grpc-curl no solo es útil para los desarrolladores, sino también para los testers, los ingenieros de QA, los ingenieros de DevOps y cualquier persona que necesite interactuar con los servidores gRPC. Puede ayudarte a verificar la funcionalidad, el rendimiento, la seguridad y la fiabilidad de tus APIs, e identificar y corregir cualquier problema o error.
¿Cómo usar grpc-curl con apidog?
Si quieres llevar tus pruebas y depuración de gRPC al siguiente nivel, es posible que quieras usar grpc-curl con apidog, una herramienta potente y flexible para la documentación y prueba de APIs.
Apidog es una herramienta que te permite crear, gestionar y compartir documentación y pruebas de APIs, utilizando una interfaz sencilla e intuitiva. Puedes usar apidog para documentar y probar cualquier tipo de API, incluyendo REST, SOAP, GraphQL y gRPC.
Con apidog, puedes:
- Importar el esquema de tu API desde varias fuentes, como OpenAPI, Swagger, WSDL, GraphQL o archivos protoset.
- Crear y organizar tus endpoints de API, métodos, parámetros, cabeceras y respuestas, usando un editor gráfico o un editor de código.
- Añadir descripciones, ejemplos, validaciones y anotaciones a tus elementos de API, usando Markdown o HTML.
- Generar documentación de API interactiva y atractiva, con ejemplos en vivo, fragmentos de código y diagramas.
- Crear y ejecutar pruebas de API, usando un ejecutor de pruebas integrado o una herramienta de línea de comandos.
- Monitorizar y depurar tus llamadas a la API, usando un proxy integrado o una extensión del navegador.
- Colaborar y compartir tus proyectos de API con tu equipo o tus clientes, usando una plataforma basada en la nube o una solución autoalojada.
Transmisión del servidor
La transmisión del servidor, como su nombre indica, implica el envío de múltiples datos de respuesta en una sola solicitud. Por ejemplo, podría implicar la suscripción a todos los datos de precios de transacción de acciones dentro de un plazo de un minuto.
Transmisión del cliente
En este modo, el cliente puede enviar continuamente múltiples mensajes de solicitud al servidor sin esperar respuestas inmediatas. Después de procesar todas las solicitudes, el servidor envía un único mensaje de respuesta al cliente. Este enfoque es muy adecuado para transmitir eficientemente grandes cantidades de datos de forma continua, lo que ayuda a reducir la latencia y optimizar el intercambio de datos.
Transmisión bidireccional
La transmisión bidireccional permite a los clientes y servidores establecer una comunicación bidireccional persistente y transmitir múltiples mensajes simultáneamente. Se emplea comúnmente en juegos en línea y software de videollamadas en tiempo real, y es muy adecuado para la comunicación en tiempo real y escenarios de transmisión de datos a gran escala. Después de iniciar la llamada, el cliente y el servidor mantienen una sesión entre ellos y reciben respuestas en tiempo real después de enviar diferentes contenidos de solicitud.
Colaboración en APIs gRPC
Apidog puede generar documentos de interfaz gRPC legibles por humanos a partir de archivos .proto, lo que facilita la colaboración en equipo en las interfaces. Haz clic en el botón de menú en el lado derecho de la interfaz para obtener el enlace de colaboración y compartirlo con otros miembros del equipo para alinear el enfoque de depuración de la interfaz.
- Crea una cuenta de apidog e inicia sesión en la aplicación web de apidog.
- Crea un nuevo proyecto de API y dale un nombre y una descripción.
- Importa el esquema de tu gRPC desde un archivo protoset, o créalo manualmente usando el editor gráfico o el editor de código.
- Añade tus endpoints, métodos, parámetros, cabeceras y respuestas de gRPC, y rellena los detalles y los ejemplos.
- Genera la documentación de tu API y visualízala en el navegador o expórtala como un archivo PDF o HTML.
- Crea tus pruebas de API y ejecútalas usando el ejecutor de pruebas integrado o la herramienta de línea de comandos.
- Monitoriza y depura tus llamadas a la API, usando el proxy integrado o la extensión del navegador.
- Comparte tu proyecto de API con tu equipo o tus clientes, usando la plataforma basada en la nube o la solución autoalojada.
Para obtener más información sobre apidog y cómo usarlo con grpc-curl, puedes visitar el sitio web de apidog o consultar la documentación de apidog.
Conclusión
grpc-curl es una herramienta de línea de comandos que te permite interactuar con los servidores gRPC de una manera sencilla e intuitiva. Se basa en gRPCurl, pero añade algunas características y mejoras que lo hacen más fácil de usar y potente. Puedes usar grpc-curl para probar y depurar tus APIs gRPC, y para generar fragmentos de código para tu propio código de cliente.
grpc-curl también es compatible con apidog, una herramienta basada en la web para la documentación y prueba de APIs. Puedes usar apidog para crear, gestionar y compartir tus proyectos de API, y para ejecutar y monitorizar tus pruebas de API.
Si eres un desarrollador que trabaja con gRPC, o si estás interesado en aprender más sobre gRPC, definitivamente deberías probar grpc-curl y Apidog. Pueden ayudarte a mejorar la calidad y la usabilidad de tus APIs, y hacer que tu proceso de desarrollo sea más fácil y rápido.
