gRPC API Proxy Creation

You can manage and securely expose your gRPC services through the Apinizer platform. You can use the high-performance RPC framework developed by Google, work with Protocol Buffers (protobuf) format. You can create gRPC API Proxy from protobuf file, import proto file, define services and methods, and configure routing

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:

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

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:

   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.

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

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

Scenario 1: Exposing Internal gRPC Service

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.

Scenario 2: gRPC Service Versioning

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.

Scenario 3: Converting gRPC to REST

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

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 service definitions 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).

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