Implementation of gRPC services

To implement gRPC services through the API object, you must configure its gRPC Protocol property with value True.

Upon doing Build, GeneXus automatically generates the following:

• The .proto files in folder <ModelKB>\web\proto.
• The base code for the protoc compiler.
• The code that implements the services interface and the logic of services.  

Therefore, you must only be concerned with deciding where the service will be lifted. To do so, you have two options:

• Interface on the web. 
• Using command line.

Interface on the web

You may select this option for both the Java generator and the .NET generator. 

You just need to set up gRPC Protocol property = True, and Generate OpenAPI interface property = No.

Then execute the API object, by right clicking on it.  This will generate, in your browser, an interactive web interface for gRPC like the one below:

Use command lines 

You can use a command line tool that provides interaction with the gRPC services, such as gRPCurl. 

The first thing to do is, for the API object, set up gRPC Protocol property = True and to a Build for GeneXus to generate the files required. 

The procedure will be different depending on the generator that you use (Java or .NET).

Java Generator

From the toolbar, go to: Tools>CMD Environment Directory.

Then add the line shown below and press enter:

cd Web\build\classes\java\main

This folder contains the compiled code.

You should then execute the following line to lift the server:

java -cp ./;../../../libs/*  com.<gRPC Package>.<API object name>grpcserver

The libs folder has all the java libraries and jars necessary to execute any proc command line. And you must indicate the value given to gRPC Package property, as well as the name of your API object with the suffix grpcserver. 

For example, if the value of gRPC Package is KBAPIobjectgRPC and the name of the API object is APICustomer, then you will have to enter the following:

java -cp ./;../../../libs/* com.kbapiobjectgrpc.apicustomergrpcserver

If everything is fine you will get a message like this:

com.kbapiobjectgrpc.apicustomergrpcserver start
INFO: Server started, listening on 50051

This is an indication that you may run the service already.  

If you wish, for example, to run the service with the gRPCurl tool you must go to the toolbar, Tools>CMD Environment Directory, and run the following:

cd Web

This is where the proto folder is located, containing the .proto files. 

Then execute the following line:

<path grpCurl> -plaintext -import-path ./proto -proto <API object name>.proto -d "{\"var\": value, \"var\": \"steingvalue\"}" localhost:<port> <gRPC Package>.<Services base path>

First you indicate the address of the .exe of gRPCurl. And immediately following that indicate the address and name of the .proto file. You will have to indicate the parameters according to you API’s definition. And last, you will specify the port and the values of gRPC Package property and Services base path property.

Sample

When you have defined an API object as follows:

Customer
{
 InsertNewCustomer(in:&CustomerId, in:&CustomerName, in:&CustomerLastName, out:&Customer)
 => InsertNewCustomer(in:&CustomerId, in:&CustomerName, in:&CustomerLastName, out:&Customer);
}

And also if the value of the gRPC Package is KBAPIobjectgRPC, and the value of Services base path property is APICustomer, then your command should be the one below:

C:\grpCurl\grpcurl -plaintext -import-path ./proto -proto apicustomer.proto -d "{\"customerid\": 1, \"customername\": \"Simon\", \"customerlastname\" : \"Taylor\" } " localhost:50051 KBAPIobjectgRPC.APICustomer/InsertNewCustomer

If everything is correct you will be getting this:

{
  "customer": {
  "customerid": 1, 
  "customername": "Simon",
  "customerlastname": "Taylor"
  }
}

NET Generator

Lifting the service in .NET is much easier, because a .exe is generated in the /web/bin folder.

From the toolbar go to: Tools > Explore Target Environment Directory to open the file explorer in the web folder. Then go to the bin folder to find the API object name file with suffix _grpc.exe and double click on it. For instance, if the name of the API object is APICustomer, then the file will be apicustomer_grpc.exe.

When the server has been lifted correctly you will get something like this:

This is an indication that you may already run the service. 

So, as in the case of Java, you may run the service with the gRPCurl tool.

Return to the toolbar, Tools>CMD Environment Directory, and run the following:

cd Web

That is the location of the proto folder, which contains the .proto files. 

Then execute the following line:

<path grpCurl> -insecure -import-path ./proto -proto <API object name>.proto -d "{\"var\": value, \"var\": \"steingvalue\"}" localhost:<port> <gRPC Package>.<Services base path>

Note that it is similar to Java. The only thing different is that you must add insecure, to indicate that there is no security schema defined.  

Considerations

• GeneXus makes it possible to model API services accessible to both gRPC and REST protocols. This means that the implementation of API REST and API gRPC are independent, so you may implement one of them or both at the same time, and the consumer of the services decides according to personal needs.  
• gRPC services are not secured by GAM (and the corresponding API object properties). They must be secured by other means (infrastructure or additional programming).

Availability

This functionality is available as Beta since GeneXus 18 upgrade 1.

See Also

API object Syntax
Test gRPC services with Postman or gRPCurl in ASP.NET Core