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.
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:
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).
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.
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"
}
}
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.
- 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).
This functionality is available as Beta since GeneXus 18 upgrade 1.
API object Syntax
Test gRPC services with Postman or gRPCurl in ASP.NET Core