🚧

The gRPC behavior is in Beta and has limited functionality.

This behavior turns on support for native gRPC (Google Remote Procedure Call)--an open-source, high-performance RPC framework that uses Protocol Buffers (protobuf) to transmit data. Developed by Google as an update to RPC protocol, gRPC enables function calls across processes and is widely used to connect large numbers of microservices.

Unlike traditional APIs that transmit JSON or XML, gRPC messages using protobuf are smaller and faster, while supporting large amounts of programming libraries and tooling. gRPC is built on HTTP/2, supports multiplexed streams, and four communication patterns:

• Request-response (also known as unary), where the number of request RPC messages equals the number of response RPC messages
• Server streaming
• Client streaming
• Bidirectional streaming

📘

gRPC-Web is supported by Akamai by default.

Before you begin

The gRPC behavior must be added to your contract before you can use it in your rule configurations. Talk with your account team to enable gRPC.

Why you need it

gRPC enables efficient, low-latency communication between internal microservices–an essential component of scalable and responsive architectures. Its high-performance APIs are well-suited for mobile backends and real-time systems. It also supports real-time data transfer, making it ideal for chat applications, telemetry data, video conferencing, and other live update use cases. For example:

• A ride-sharing app can use gRPC to continuously send GPS data from a user’s phone to a backend while receiving real-time updates about nearby drivers.
• Using gRPC, a live, web-based dashboard can stream stock market data directly from a backend service.
• gRPC’s bidirectional streaming further enhances conversational AI applications by allowing a client to send prompts and receive responses on a token-by-token basis from an LLM with minimal latency.

Additionally, gRPC’s automatic code generation, powered by the protoc compiler, creates client and server code using a vast array of programming languages. This helps catch errors during compile-time instead of at runtime, reduce repetitive code, and save development time.

How it works

The communication mechanism used by gRPC, protobuf, is both language- and platform-agnostic, enabling gRPC to encode structured data into a compact binary format. Developers define schemas and parameters in a .proto file, which protobuf uses to generate data access classes. Clients use these classes to make RPC calls, while servers use them to fulfill RPC requests. Because protobuf supports most popular programming languages, clients and servers can choose the language that best fit their individual needs.

gRPC communication uses HTTP/2 POST requests with a Content-Type of application/grpc and a binary-encoded request body, usually returning an HTTP status of 200 OK. The final call status and any error details are provided in HTTP/2 trailers, such as grpc-status and grpc-message, which are part of the HTTP/2 stream rather than the HTTP status code.

Key features:

• Transport: Uses HTTP/2, enabling multiplexed streams and concurrent RPC calls over a single connection.
• Serialization: Uses Protocol Buffers (protobuf) for compact, efficient binary serialization.
• Cross-language support: Works with C++, Java, Python, Go, Node.js, C#, and most other programming languages.
• Streaming support
  • Unary RPC: One for one; the number of messages in the request equals the number of messages in the response
  • Server streaming: One message per-request, many messages per-response
  • Client streaming: Any messages per-request, one message per-response
  • Bidirectional streaming: Many messages per-request and many messages per-response over one request/response, request and response are in parallel.
• Security: Supports TLS encryption for secure communication.
• Automatic code generation: The .proto file serves as the source of truth for generating client and server stubs–the code snippets that govern RPC-based communication.

gRPC status codes

Each RPC call results in a status that gets returned to the client made up of an integer code and a string error description. The server-side chooses the status that’s returned for a given RPC call.

For a full list of status codes, ID numbers, and descriptions see the official gRPC documentation.

Features and options

Enabling the gRPC behavior turns on support for native gRPC. The Enable Bidirectional Streaming option turns on the ability to transmit multiple messages per request and response.

Implementation

Required settings

The following settings must be configured for the gRPC behavior to function properly:

• HTTP/2 and Allow POST must be enabled in the current or the parent rule.
• HTTP/2 in the Origin Server must be enabled in the current or the parent rule.
• Enable Bidirectional Streaming can be only enabled under a Path match condition.
• gRPC requires the caching option to Bypass cache.

Example 1: Create a parent rule for general gRPC traffic

To configure gRPC, you can use it with common match criteria like Path to apply settings to certain gRPC endpoints. In your rule tree, create a rule that matches all gRPC traffic for a given service. In this rule, enable only the primary gRPC toggle. Replace /StockService/* with your own endpoint:

• Match: Path matches /StockService/*
• Behavior
  • gRPC Enable: On
  • Enable Bidirectional Streaming: Off

Example 2: Create a nested rule for bidirectional endpoints

If you need to configure a service with both unary and bidirectional endpoints, use a parent rule for general traffic and nest child rules for the specific bidirectional endpoints. In this example, the parent rule (gRPC) match uses the Path /StockService/*, and the nested child rule (Bidirectional Streaming) matches subdirectories of that endpoint, /StockService/BidiEndpoint1/* and /StockService/BidiEndpoint2/*.

This structure ensures that any request to a bidirectional endpoint matches both the parent and the child rule, with the more specific child rules’ settings taking precedence. All other requests under /StockService/ will only match the parent rule and be treated as standard gRPC.

📘

Specify your endpoints for best performance

It’s important to be specific about your bidirectional endpoints and making sure the right traffic is going to the right endpoint. For best results, endpoints for bidirectional traffic should be separate from endpoints for non-bidirectional traffic.

In your rule tree, create a nested child rule for Bidirectional Streaming within the parent gRPC rule. This rule should specifically match only the paths of your bidirectional endpoints. In this case, you need to enable both gRPC behavior toggles. Replace /StockService/BidiEndpoint1/* and /StockService/BidiEndpoint2/* with your own endpoints:

• Match: Path matches /StockService/BidiEndpoint1/*, /StockService/BidiEndpoint2/*
• Behavior
  • gRPC Enable: On
  • Enable Bidirectional Streaming: On

Caveats and known issues

Consider the following items before setting up this support.