gRPC API Proxy Creation
gRPC API Proxy performs message processing in Protocol Buffers (protobuf) format. This format is more compact and faster than JSON.
gRPC runs on HTTP/2 protocol and provides multiplexing support.
Supports Unary, Server Streaming, Client Streaming, and Bidirectional Streaming methods.
Provides higher performance than JSON thanks to binary protobuf format.
gRPC API Proxy Creation Methods
There are several methods to create a gRPC API Proxy:
Import from Protobuf (.proto) File
The most common method is to import from a protobuf (.proto) file. This method automatically imports your services, methods, and message types.
Manual Creation
You can also manually create a gRPC API Proxy without a protobuf file. In this case, you need to manually define services and methods.
Copy from Existing API Proxy
You can create a new proxy by copying an existing gRPC API Proxy. This method saves time for similar services.
Import from Protobuf File
Development → API Proxies item is selected in the main menu on the left. The +Create button at the top right of the opened interface is clicked and gRPC API option is selected.
There are three methods to upload a protobuf file:
Method 1: File Upload
The Upload File button is clicked. A .proto file is selected from your computer. The file is automatically parsed and service information is displayed.
Protobuf File Format A protobuf file is a file that defines your gRPC services. The file contains definitions such as service, rpc, message.
Method 2: Load from URL
The Enter URL link is clicked. The URL of the protobuf file is entered and the Parse button is clicked. The file is parsed and service information is displayed.
Authentication and SSL If the spec URL requires authentication, enable Use Spec Authorization to enter custom headers or Basic Auth (username/password). In the SSL / Certificate Settings panel, configure Connection Timeout, Customize SSL/TLS Settings, Skip SSL Verification, and Server Certificate Verification (System Default, TrustStore, or PEM) for HTTPS access. For details, see API Proxy Creation.
Method 3: Paste as Text
The Paste as Text option is selected. The protobuf content is pasted into the text field and the Parse button is clicked. The content is parsed and service information is displayed.
After the parse operation is completed, the following information is displayed:
Protobuf package name
All gRPC services
RPC methods for each service
Request and response message types
Unary, Server Streaming, Client Streaming, or Bidirectional Streaming
Client Route (Relative Path)
Client Route is the endpoint where the API Proxy is exposed to the outside world. Clients access the gRPC service through this endpoint.
Example:
Relative Path: /grpc/user-service
In this case, the gRPC service is accessed as follows:
{apinizer-gateway}/grpc/user-service
Upstream Target (Backend Address)
Upstream Target is the address of your backend gRPC service. The API Proxy routes requests to this address.
Configuration Format:
host:port
Example:
backend-grpc.example.com:50051
gRPC Port gRPC services usually run on special ports like 50051. Make sure you correctly specify the port number of your backend service.
Special routing configuration can be made for gRPC. For more information, you can refer to the gRPC Routing page.
All information is checked. The Relative Path field is filled (required). Upstream Target information is entered (in host:port format). The Save button at the top right is clicked.
gRPC API Proxy created successfully!
Protobuf File Structure
A protobuf file generally has the following structure:
syntax = "proto3";
package com.example.service;
// Message definitions
message UserRequest {
string user_id = 1;
}
message UserResponse {
string user_id = 1;
string name = 2;
string email = 3;
}
// Service definition
service UserService {
// Unary RPC
rpc GetUser(UserRequest) returns (UserResponse);
// Server Streaming RPC
rpc ListUsers(UserRequest) returns (stream UserResponse);
// Client Streaming RPC
rpc CreateUsers(stream UserRequest) returns (UserResponse);
// Bidirectional Streaming RPC
rpc ChatUsers(stream UserRequest) returns (stream UserResponse);
}
gRPC Method Types
gRPC supports four different method types:
Single request, single response. The most commonly used method type.
Example:
rpc GetUser(UserRequest) returns (UserResponse);
Single request, multiple responses. Server sends a stream.
Example:
rpc ListUsers(UserRequest) returns (stream UserResponse);
Multiple requests, single response. Client sends a stream.
Example:
rpc CreateUsers(stream UserRequest) returns (UserResponse);
Multiple requests, multiple responses. Both sides send streams.
Example:
rpc ChatUsers(stream UserRequest) returns (stream UserResponse);
Post-Import Configuration
After the API Proxy is created, the following configurations can be made:
gRPC Routing determines how methods will be routed.
Policies such as security, validation, transformation can be added to the API Proxy.
Some policies can be specifically applied for gRPC. For example, policies for validating or transforming protobuf messages.
gRPC API Proxy can be tested. Apinizer Test Console provides gRPC test support.
API Proxy can be deployed to environment(s).
Common Scenarios
Scenario 1: Exposing Internal gRPC Service
To expose an internal gRPC service to the outside world:
The .proto file of your gRPC service is uploaded.
Relative Path is determined (for example: /grpc/user-service).
The address of the internal service is used as Upstream Target (for example: internal-grpc.example.com:50051).
Security policies such as mTLS, Authentication are added.
API Proxy is saved and deployed.
Scenario 2: gRPC Service Versioning
To create separate API Proxies for different versions:
A separate .proto file is used for each version.
Different Relative Paths are used (for example: /grpc/v1/user-service, /grpc/v2/user-service).
Separate policies are defined for each version.
Migration strategy between versions is determined.
Scenario 3: Converting gRPC to REST
To expose a gRPC service as a REST API:
A gRPC API Proxy is created.
REST transformation policies are added.
gRPC methods are mapped to REST endpoints.
Request/Response transformations are configured.
Best Practices
Make sure your protobuf file is valid and up-to-date. Invalid files may cause errors during import.
Use a consistent naming convention for Relative Paths. For example: /grpc/{service-name}/{version}
Define backend addresses as environment variables. This provides flexibility for different environments.
Always use mTLS (mutual TLS) security for gRPC. gRPC services usually run on internal networks and security is critical.
Optimize performance for streaming methods. Optimize buffer settings for large data streams.
Handle gRPC error codes (status codes) correctly. gRPC uses a different error system than HTTP status codes.
Troubleshooting
Import Error
Problem: Protobuf file cannot be imported.
Solution:
- Make sure the protobuf file has valid syntax (proto2 or proto3).
- Make sure all dependencies of the file (imported files) are present.
- Check URL accessibility.
- Make sure the file size is within the limit.
Services Not Visible
Problem: Services are not visible after import.
Solution:
- Make sure
servicedefinitions in the protobuf file are correct. - Check that the package name is correctly defined.
- Check that RPC methods are correctly defined.
Routing Error
Problem: Requests are not routed to backend.
Solution:
- Make sure the Upstream Target address is in the correct format (host:port).
- Check that your backend gRPC service is accessible.
- Check gRPC Routing configuration.
- Make sure the port number is correct.
Streaming Error
Problem: Streaming methods are not working.
Solution:
- Check that streaming methods are correctly defined.
- Make sure HTTP/2 support is active.
- Check timeout settings (longer timeout may be required for streaming).