If you’re a developer who works with APIs, you probably know how important it is to test and debug them before deploying them to production. You want to make sure that your APIs are reliable, secure, and performant, and that they meet the expectations of your clients and users.
But how do you test and debug your APIs, especially if they use gRPC , a modern and efficient protocol for communication between microservices? That’s where grpc-curl comes in. grpc-curl is a command-line tool that lets you interact with gRPC servers simply and intuitively.
In this blog post, I’ll show you how to use grpc-curl to test and debug your APIs, and why you should consider using it for your gRPC projects.
What is grpc-curl?
g rpc-curl is a command-line tool that lets you invoke RPC methods on a gRPC server from the command-line. It supports various RPC methods, including unary, server-streaming, client-streaming, and bi-directional streaming. You can also browse the schema for gRPC services, either by querying a server that supports server reflection or by loading in compiled protoset files.
fullstorydev
grpc-curl is written in .NET, and it has some advantages over gRPCurl, such as:
- It supports both .NET Core and .NET Framework, and it can run on Windows, Linux, and Mac OS.
- It has a more concise and expressive syntax, and it can infer the service and method names from the URL.
- It can automatically format the JSON output with colors and indentation, and it can also output XML or plain text.
- It can handle nested messages and repeated fields better, and it can also accept input from files or standard input.
- It can use environment variables for common options, such as the server URL, the headers, and the TLS settings.
- It can generate code snippets for C#, Java, Python, and Go, to help you write your own client code.
grpc-curl is available as a NuGet package, and you can install it with the following command:
dotnet tool install -g grpc-curl
How to Use grpc-curl?
To use grpc-curl, you need to have a gRPC server running, and you need to know its URL and the service and method names that you want to call. You also need to have the schema for the gRPC services, either by using server reflection or by loading protoset files.
For this example, I’ll use a simple gRPC server that implements a calculator service, with four methods: Add, Subtract, Multiply, and Divide. The server is written in C#, and it supports server reflection.
To start the server, run the following command from the project folder:
dotnet run
The server will listen on port 5000 by default. You can change the port number in the appsettings.json file.
To call the Add method on the server, run the following command from another terminal:
grpc-curl http://localhost:5000 Calculator/Add -d '{"x": 3, "y": 5}'
The output should look something like this:
{
"result": 8
As you can see, grpc-curl automatically infers the service and method names from the URL, and it formats the JSON output with colors and indentation. You can also use the -o option to specify a different output format, such as xml or text.
To call the Subtract method, run the following command:
grpc-curl http://localhost:5000 Calculator/Subtract -d '{"x": 10, "y": 4}'
The output should look something like this:
{
"result": 6
To call the Multiply method, run the following command:
grpc-curl http://localhost:5000 Calculator/Multiply -d '{"x": 2, "y": 7}'
The output should look something like this:
{
"result": 14
To call the Divide method, run the following command:
grpc-curl http://localhost:5000 Calculator/Divide -d '{"x": 15, "y": 3}'
The output should look something like this:
{
"result": 5
If you try to divide by zero, you’ll get an error message, like this:
grpc-curl http://localhost:5000 Calculator/Divide -d '{"x": 15, "y": 0}'
"error": "Cannot divide by zero."
grpc-curl also supports streaming methods, which can send or receive multiple messages in a single call. For example, let’s say we have a server-streaming method called Fibonacci, which takes a number n as input and returns the first n Fibonacci numbers as a stream of messages. The server code for this method looks something like this:
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;
To call this method with grpc-curl, run the following command:
grpc-curl http://localhost:5000 Calculator/Fibonacci -d '{"value": 10}'
The output should look something like this:
{
"value": 0
"value": 1
"value": 1
"value": 2
"value": 3
"value": 5
"value": 8
"value": 13
"value": 21
"value": 34
As you can see, grpc-curl prints each message as it receives it from the server, and it closes the connection when the stream is complete.
grpc-curl also supports client-streaming methods, which can send multiple messages to the server and receive a single response. For example, let’s say we have a client-streaming method called Sum, which takes a stream of numbers as input and returns their sum as a response. The server code for this method looks something like this:
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 };
To call this method with grpc-curl, we need to provide the input messages from a file or from standard input. For example, we can create a file called numbers.json with the following content:
{"value": 1}
{"value": 2}
{"value": 3}
{"value": 4}
{"value": 5}
Then, we can run the following command:
grpc-curl http://localhost:5000 Calculator/Sum -d @numbers.json
The output should look something like this:
{
"value": 15
Alternatively, we can use the - symbol to indicate that the input messages are coming from standard input, and then type or paste the messages in the terminal, followed by Ctrl+D to end the input. For example:
grpc-curl http://localhost:5000 Calculator/Sum -d -
{"value": 1}
{"value": 2}
{"value": 3}
{"value": 4}
{"value": 5}
The output should be the same as before.
grpc-curl also supports bi-directional streaming methods, which can send and receive multiple messages in both directions. For example, let’s say we have a bi-directional streaming method called Chat, which takes a stream of messages as input and returns a stream of messages as output. The server code for this method looks something like this:
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}");
To call this method with grpc-curl, we need to provide the input messages from a file or from standard input, and we need to use the -s option to indicate that we want to receive the output messages as a stream. For example, we can create a file called chat.json with the following content:
{"text": "Hello"}
{"text": "How are you?"}
{"text": "Goodbye"}
Then, we can run the following command:
grpc-curl http://localhost:5000 Calculator/Chat -d @chat.json -s
The output should look something like this:
{
"text": "Echo: Hello"