Skip to main content

Protobuf Format

gRPC API Proxy performs message processing in Protocol Buffers (protobuf) format. This format is more compact and faster than JSON.

HTTP/2 Protocol

gRPC runs on HTTP/2 protocol and provides multiplexing support.

Streaming Support

Supports Unary, Server Streaming, Client Streaming, and Bidirectional Streaming methods.

High Performance

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:
The most common method is to import from a protobuf (.proto) file. This method automatically imports your services, methods, and message types.
You can also manually create a gRPC API Proxy without a protobuf file. In this case, you need to manually define services and methods.
You can create a new proxy by copying an existing gRPC API Proxy. This method saves time for similar services.

​
Import from Protobuf File

1

Go to API Proxy Creation Page

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.
2

Upload Protobuf File

There are three methods to upload a protobuf file:
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.
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.
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.
3

Check Service Information

After the parse operation is completed, the following information is displayed:

Package

Protobuf package name

Services

All gRPC services

Methods

RPC methods for each service

Message Types

Request and response message types

Streaming Type

Unary, Server Streaming, Client Streaming, or Bidirectional Streaming
4

Routing Configuration

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 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.
5

gRPC Routing Configuration

Special routing configuration can be made for gRPC. For more information, you can refer to the gRPC Routing page.
6

Save API Proxy

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:

Unary RPC

Single request, single response. The most commonly used method type.Example:
rpc GetUser(UserRequest) returns (UserResponse);

Server Streaming RPC

Single request, multiple responses. Server sends a stream.Example:
rpc ListUsers(UserRequest) returns (stream UserResponse);

Client Streaming RPC

Multiple requests, single response. Client sends a stream.Example:
rpc CreateUsers(stream UserRequest) returns (UserResponse);

Bidirectional Streaming RPC

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 Configuration

gRPC Routing determines how methods will be routed.

Adding Policies

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.

Testing

gRPC API Proxy can be tested. Apinizer Test Console provides gRPC test support.

Deployment and Version

API Proxy can be deployed to environment(s).

​
Common Scenarios

To expose an internal gRPC service to the outside world:
1

Upload Proto File

The .proto file of your gRPC service is uploaded.
2

Determine Relative Path

Relative Path is determined (for example: /grpc/user-service).
3

Set Upstream Target

The address of the internal service is used as Upstream Target (for example: internal-grpc.example.com:50051).
4

Add Security Policies

Security policies such as mTLS, Authentication are added.
5

Save and Deploy

API Proxy is saved and deployed.
To create separate API Proxies for different versions:
1

Separate Proto File for Each Version

A separate .proto file is used for each version.
2

Different Relative Paths

Different Relative Paths are used (for example: /grpc/v1/user-service, /grpc/v2/user-service).
3

Separate Policies

Separate policies are defined for each version.
4

Migration Strategy

Migration strategy between versions is determined.
To expose a gRPC service as a REST API:
1

Create gRPC API Proxy

A gRPC API Proxy is created.
2

REST Transformation Policies

REST transformation policies are added.
3

Map Methods

gRPC methods are mapped to REST endpoints.
4

Configure Transformations

Request/Response transformations are configured.

​
Best Practices

Protobuf File Quality

Make sure your protobuf file is valid and up-to-date. Invalid files may cause errors during import.

Relative Path Strategy

Use a consistent naming convention for Relative Paths. For example: /grpc/{service-name}/{version}

Backend Address

Define backend addresses as environment variables. This provides flexibility for different environments.

mTLS Security

Always use mTLS (mutual TLS) security for gRPC. gRPC services usually run on internal networks and security is critical.

Streaming Performance

Optimize performance for streaming methods. Optimize buffer settings for large data streams.

Error Handling

Handle gRPC error codes (status codes) correctly. gRPC uses a different error system than HTTP status codes.

​
Troubleshooting

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.
Problem: Services are not visible after import.Solution:
  • Make sure service definitions in the protobuf file are correct.
  • Check that the package name is correctly defined.
  • Check that RPC methods are correctly defined.
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.
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).

​
Next Steps

gRPC Routing

Learn gRPC Routing configuration

Policy Management

Learn to add policies

mTLS Security

Learn about mTLS security

Deployment and Version

Learn to deploy