Implementing gRPC Clients

The topics below explain how to implement a gRPC service and write a client to invoke it.

After completing the gRPC service implementation, you can call these service methods using a client as follows.

Execute the bal new client command to create a Ballerina package to implement the client. You view the output below.

Created new Ballerina package 'client' at client.

Execute the bal grpc --mode client --input admin.proto --output client/ command to create the service stub/client. You view the output below.

Successfully extracted library files.
Successfully generated ballerina file.

The service stub/client is generated in the client default module directory. The AdminService_sample_client.bal file contains sample code instantiating the gRPC client to access the remote service as follows.

AdminServiceClient ep = check new("http://localhost:9090");

public function main () {


The ep object contains the remote functions that correspond to the gRPC service methods. The diagram below shows the VS Code code assist in listing the methods.

Admin Service Client Remote Functions List

Complete the automatically-generated code in the client module of the AdminService_sample_client.bal file. The completed gRPC client code, which invokes all the methods defined in the service is as follows.

import ballerina/io;

AdminServiceClient adminServiceClient = check new("http://localhost:9090");

public function main () returns error? {
   AddResponse addResult = check adminServiceClient->add({ numbers: [1, 2, 3, 4] });
   io:println("Add Result: ", addResult.result);
   MultiplyResponse mulResult = check adminServiceClient->multiply({ v1: 5, v2: 7 });
   io:println("Multiply Result: ", mulResult.result);
   Person person = { name: "Jack Dawson", birthYear: 1990 };
   AddPersonResponse addPersonResult = check adminServiceClient->addPerson(person);
   io:println("Add Person Result: ",;
   Person getPersonResult = check adminServiceClient->getPerson({ id: });
   io:println("Get Person Result: ", getPersonResult);

Executing the Implementations

After completing the full code for both the client and the service, you can execute them by building and running both modules from the Ballerina project root directory as follows.

  1. Execute the bal run service command to start the gRPC service. You view the output below.

    Compiling source
    Creating the BALA file
    Running executable
    [ballerina/grpc] started HTTP/WS listener

    Info: The gRPC service is up and running at port 9090.

  2. Execute the bal run client command to run the client module, which will try to contact the active service. You view the output below.

    Compiling source
    Creating the BALA file
    Running executable
    Add Result: 10
    Multiply Result: 35
    Add Person Result: eb8d852a-7988-4404-8f7e-173544f2af79
    Get Person Result: {"id":"eb8d852a-7988-4404-8f7e-173544f2af79","name":"Jack Dawson","birthYear":1990}

Now, the client will establish a connection with the gRPC service, invoke the methods in it, and receive the respective response messages.

What’s Next?

For information on gRPC streaming, see Performing gRPC Streaming.