Apache APISIX gRPC transcoding

Apache APISIX can expose gRPC services as REST endpoints for browser and mobile clients without changing the services. This page covers how the grpc-transcode plugin works, what to plan, and what to confirm before you build.

Book a callTalk to us
On this page

When APISIX gRPC transcoding fits your REST and gRPC estate

The grpc-transcode plugin lets APISIX accept REST or JSON requests and forward them to internal gRPC services, so browser and partner clients can call those services without speaking gRPC themselves. Teams need it when their services are gRPC-only, the callers cannot use gRPC directly, and they want the translation handled at the gateway. APISIX is built on NGINX and etcd, its repository lists gRPC among the protocols it proxies, and transcoding is one of the more than 100 built-in plugins described in its documentation. The plugin is a fit only if those three facts match your estate.

Before you commit, map which clients need REST access, which gRPC services they must reach, and who will own the translation rules. Decide whether transcoding at the gateway is better placed than changing the services themselves, or than exposing gRPC-Web for browser callers. Confirm which gRPC call types your target APISIX version supports through the plugin, because the answer determines whether streaming methods can be exposed at all. Ask the team that owns each service whether its proto files are stable enough to load into the gateway, since every change to those files becomes a gateway change.

The plugin is a poor fit if most of your callers already speak gRPC, if the gateway team cannot take on proto file management, or if the services are still changing their contracts often. In those cases a direct gRPC route through the gateway, or a REST layer maintained inside the service, may cost less to run. Confirm the exact behavior, supported options and limits in the plugin documentation for your chosen release, and test one representative method end to end before you agree on scope for the full estate.

Configuration options and when each fits

This table compares the main configuration choices for gRPC transcoding in APISIX: where proto definitions live, how routes map to services and methods, how multiple descriptors are combined, and how the gateway reaches the upstream. Read each row against your team's proto ownership and network model, then confirm the exact field names and supported options in the grpc-transcode plugin documentation for the APISIX release you plan to run.

OptionWhat it involvesWhen it fitsWhat to confirm
Inline proto upload in the routePaste or upload the compiled descriptor set into the route's grpc-transcode configuration, so the definition is stored with the route in etcd or the standalone configuration file.Small gateways with one or two services and a single team that owns both the routes and the protos.How the descriptor is encoded in the release you run, and how large descriptors are handled in your config store.
Descriptor set stored and referenced by a shared artifactKeep compiled descriptor sets in your artifact store or source repository and push them into APISIX through your configuration pipeline.Multiple services with separate release cycles, where proto changes must be reviewed and versioned like code.Your pipeline's push method and whether the Admin API or configuration file is the source of truth in your deployment mode.
One descriptor set per serviceEach gRPC service gets its own compiled descriptor, and routes reference the one for the service they front.Teams that own separate services and want a change in one proto to stay isolated from others.Whether the chosen plugin version accepts several descriptor files on one route, and how service names are resolved.
Combined descriptor for several proto filesCompile imported proto files into a single descriptor set so that cross-file message references resolve at the gateway.Services that share common message types or imports across several .proto files.That all imports are included when compiling, and that the descriptor is rebuilt whenever a shared file changes.
Route per service and methodMap each HTTP path and method to one gRPC service method, so REST clients call a predictable URL.Public or partner REST APIs where a small set of methods is exposed deliberately.The exact mapping fields for service name, method name and HTTP path, and how unmapped methods are rejected.
Route per service with method passthroughMap a service broadly and let more methods reach the upstream without a separate route each.Internal browser or mobile clients on a stable service with few methods, where route count is the main concern.Whether broad mapping widens exposure of methods you did not intend to publish, and how to restrict them.
Plaintext connection to the upstreamAPISIX calls the gRPC service without TLS on the internal link.Only on a private segment where the network controls the path and the service has no TLS listener.Your network policy for that segment and whether your audit scope accepts unencrypted internal traffic.
TLS to the upstream with certificate verificationAPISIX connects to the gRPC service over TLS and verifies the server certificate against a trusted CA.Default choice for regulated traffic or any path that crosses a zone boundary.How the upstream TLS and CA settings are configured in your release, and where certificates are stored and rotated.
Mutual TLS to the upstreamAPISIX presents a client certificate to the gRPC service, which verifies it before accepting calls.Zero-trust segments or services that require caller identity at the transport layer.Certificate issuance, rotation, and whether the gateway's client certificate is protected like other secrets.

Setup sequence for a transcoded route

This sequence takes a gRPC service that already has versioned proto files and turns it into a REST or browser-facing route on APISIX. Each step ends with a check, so the team knows the route is ready before clients depend on it.

  1. Confirm proto files and service ownership

    Before touching the gateway, the service owner confirms that the proto files live in version control, that each file has a tagged release matching the deployed service, and that imports resolve without errors. Someone on the platform team should be named as the contact for descriptor changes. Done means a reviewer can point to one commit or tag that the running gRPC service was built from, and the team can compile the descriptor set from that tag on a clean machine.

  2. Deploy APISIX in the chosen mode

    The platform team deploys APISIX in the mode selected during design: traditional, decoupled or standalone, each documented in the deployment modes guide. In traditional mode, confirm that client traffic reaches port 9080 and the Admin API responds on port 9180. Confirm that the gRPC backend is reachable from the APISIX nodes, not only from your workstation. Done means a simple test route to a health endpoint returns the expected response through the gateway.

  3. Upload the proto descriptors

    Compile the proto files into a descriptor set and load it into APISIX through the Admin API or the configuration method your mode uses. Store the descriptor under a stable identifier that matches your naming convention, so later updates replace the same object instead of creating duplicates. Done means the Admin API lists the stored descriptor, and the entry shows the service and method names you expect from the proto files.

  4. Create the route with grpc-transcode

    Create a route that matches the REST path your clients will call and attach the grpc-transcode plugin, referencing the descriptor from the previous step. Point the route at the gRPC upstream. Keep the route definition in the same repository as the descriptor, so both change through review. Done means the route is saved, appears in the Admin API, and the gateway accepts requests on the configured path without configuration errors in the error log.

  5. Map the service and method

    Set the fully qualified gRPC service name and method name in the plugin configuration so each REST path and HTTP verb maps to one RPC. Check that the request and response message names match the proto definitions exactly, because a mismatch often appears only at call time. Done means a test call to each mapped path reaches the intended RPC on the backend, confirmed through backend logs or a trace, and an unmapped path returns an error rather than reaching a different method.

  6. Configure deadlines

    Set a timeout on the route and agree with the service owner on a deadline that the backend's own handlers respect. Test a deliberately slow call to confirm that the gateway returns a timeout response to the client and that the backend cancels work it no longer needs. Done means a slow-call test produces the timeout you set, and the backend log shows the call ended rather than continuing to run after the client left.

  7. Test with representative REST calls

    Run a set of REST requests that reflect real client behavior: different verbs, query parameters, request bodies with nested messages, and at least one error case such as an invalid field. Include calls from a browser origin if browsers will use the route. Done means each request returns the JSON shape and status code the API contract describes, and the test set is saved in version control so it can be rerun after every descriptor or route change.

  8. Verify int64 values in JSON responses

    Check how int64 and uint64 fields appear in the transcoded JSON. Confirm with the service owner whether those fields must be sent as numbers or strings, and compare a large value from the backend against the JSON the client receives. Some JavaScript clients lose precision above 2^53, so confirm the representation with the consumers before release. Done means a test with a value above that limit round-trips without loss in each client that will read the field.

Deadlines and int64 handling when REST clients call gRPC

Set one deadline budget across the browser or client, the gateway and the gRPC service, and test that the budget holds. A REST client sends a request with a timeout, APISIX forwards it to the upstream gRPC service, and the service runs its own handler with its own context deadline. If the client gives up before the gateway does, the gateway keeps working on a call nobody is waiting for. If the gateway times out before the service finishes, the service may still commit a write the client believes failed. Decide which layer owns the overall time limit, set the gateway and upstream timeouts so they do not expire ahead of the layer that should fail first, and make the service honor the incoming deadline. Confirm how the grpc-transcode plugin in your APISIX version passes or maps timeout and deadline information, because this behavior is version-dependent and should be verified against the plugin documentation for the release you run.

Decide how int64 fields appear in JSON before clients are built against them. Protocol Buffers int64, uint64 and fixed64 values can exceed the 53-bit integer range that JavaScript numbers represent exactly. A value such as a 64-bit account or transaction identifier can be sent as a JSON number, silently rounded in a browser, and then sent back with the wrong value. The usual options are to render these fields as strings in the JSON representation or to document that numeric fields above the safe range must be handled as strings or big integers on the client. Whichever you choose, record it in the API contract, and check how the transcoding layer serializes and parses these types for your proto definitions, including default values for zero and unset fields. Illustrative test: send the largest value your domain can produce through the gateway, read it back in a browser client, and compare it with the stored value.

Test deadlines and int64 handling with your own proto messages, not sample messages. Build a test set that covers your longest-running method, a method that returns a large int64 value, a request that exceeds the upstream timeout, and a client that disconnects mid-call. Run the same set after every APISIX upgrade and after any change to proto files, since field renames or type changes can alter the JSON shape clients receive. Ask your team to confirm, for the APISIX version you deploy, which timeout settings apply to the transcoded route and what the client sees when a deadline is exceeded. Keep the results with the proto files and gateway configuration so that the contract can be reviewed by the teams consuming it.

Choosing the deployment mode for transcoded routes

In traditional mode, the data plane and control plane run together on the same nodes and share the etcd configuration store. Client traffic arrives on port 9080, and the Admin API that accepts route and proto definitions listens on port 9180. Uploading a proto definition for grpc-transcode goes through the Admin API, so the gateway stores it alongside the route in etcd. This is the simplest setup for a single environment with one platform team.

  • Proto distribution: Proto files are uploaded through the Admin API, so every node picks them up from etcd without a file copy step.
  • Change control: Changes are made with Admin API calls, so they need an approval step and a record outside the gateway, such as a pipeline or a change ticket.
  • Access: Port 9180 must be restricted to the platform team and automation, because anyone who reaches it can change routes.
  • Rollback: Previous route and proto versions are not kept by APISIX itself, so keep exported configuration in version control.
  • Exposure: Keep the Admin API on a private network segment rather than on the public client path.

Confirm the default ports and Admin API key handling against the deployment modes documentation for your APISIX version before you write firewall rules.

Security and operational risks in transcoded APIs

Transcoding puts a gateway between REST or browser clients and internal gRPC services, so the gateway becomes the public entry point and the place where authentication, transport security and logging must hold together. The cards below cover the main risks and the APISIX control that addresses each one. Each control should be verified in your own environment before go-live.

Gateway as public entry point

Once a gRPC service is exposed through a transcoding route, the gateway is the only path clients should reach. Internal gRPC ports should not be reachable from outside the network, and the route list should be reviewed so that no internal method is published by accident. Check that every proto service you upload maps only to the methods clients are meant to call, and confirm that network policies allow traffic to the service only from the APISIX data plane.

Unauthenticated transcoded routes

A transcoded route that carries no authentication plugin exposes the gRPC method to anyone who can reach the gateway. Attach an authentication plugin such as jwt-auth or openid-connect to the route so that the check runs before the request is transcoded and forwarded. Confirm the order of plugin execution in your version, and test that a request without a valid token is rejected before any gRPC call is made.

Admin API exposure

The Admin API controls every route, upload of proto definitions and plugin setting in a traditional deployment, and it listens on a separate port from client traffic. If it is reachable from the client network, an attacker who obtains its key can change transcoding routes or disable authentication. Restrict the Admin API to a management network, replace default keys, and confirm that only the operations team can reach it.

TLS on both hops

Transcoding changes the wire format, so there are two connections to protect: client to gateway over HTTPS, and gateway to the gRPC service. Terminate TLS at the gateway with certificates your organization manages, and decide whether traffic from APISIX to the service uses TLS or a private network with a documented exception. Ask your team to confirm which connections carry tokens or personal data and that each one is encrypted.

Logging of transcoded requests

Logs written at the gateway show the REST path and the client identity, while the service logs show the gRPC method, so the two must be correlated to investigate an incident. Decide which fields are logged, and make sure request bodies containing personal or payment data are not written in full. Test that a single request can be traced from the gateway log to the service log using a shared request identifier.

Proto definition change control

The proto file uploaded to the gateway defines how JSON fields map to protobuf messages. If a service team changes a message without updating the gateway copy, clients may send requests that are misread or rejected, and sensitive fields may pass through unintended paths. Store proto files in version control, require review when they change, and record which version is active on each route.

Questions teams ask before transcoding gRPC for REST clients

What drives the effort and cost of gRPC transcoding in APISIX?

The main drivers are the number of services and methods to expose, the complexity of the proto definitions, how callers authenticate, and how much testing the mapped routes need. A small set of unary methods with simple messages is far less work than dozens of streaming methods that import shared protos from several repositories. Each service and method needs a route, a mapping to the REST path and verb, and a test that confirms the JSON request and response. Authentication design adds work when different consumers need different access. Ask any partner to price these four drivers separately in the written scope, and ask which items are one-time build work and which recur during upgrades.

How long does a gRPC transcoding project usually take?

Duration depends almost entirely on scope, so no fixed figure applies to every project. The timeline is set by the number of services in the first release, how many protos must be cleaned up or versioned before upload, whether authentication changes are part of the work, and how many client teams need to validate responses. A project covering one service with a handful of methods can be planned very differently from a gateway-wide rollout. Ask for milestones tied to specific deliverables, such as proto upload, the first mapped method passing tests, and sign-off by the client team, rather than one total number of weeks.

What does our team need to provide before the work starts?

The client team needs to supply the artifacts that define the contract and the access model. In practice this means:

  • The .proto files for each service in scope, with any imported files they depend on
  • A list of the methods to expose, with the REST path and HTTP verb each should use
  • Sample request and response payloads for each method, including edge cases such as empty fields and large numbers
  • The authentication model, including which identity provider issues tokens and which consumers call each route
  • Target environments and the people who can approve changes to the gateway

Missing protos or unclear auth rules are the most common reasons a fixed scope grows, so these should be settled in the written scope.

Can our in-house team implement gRPC transcoding without a partner?

A team that already runs APISIX and understands gRPC can usually do a small transcoding project alone, especially if the proto set is stable and only a few methods are exposed. The harder parts are proto handling, JSON mapping rules for types such as 64-bit integers, deadline behavior, and testing against each client. Teams new to APISIX should first confirm their operating model for the Admin API, configuration storage and upgrades. A partner is most useful when the scope is wide, several teams depend on the mappings, or the team needs a documented test suite and handover. Compare internal and external estimates against the same written scope.

How should we handle 64-bit integers and deadlines when exposing gRPC as REST?

Integer and deadline behavior are the two details most often missed in testing. Protobuf int64 values can exceed the range that many JavaScript clients represent exactly, so the team should decide whether those fields travel as JSON numbers or strings and test that choice with every consumer. Deadlines also need explicit handling: a REST caller usually has its own timeout, and the gateway and upstream gRPC service need timeouts that fit inside it. Confirm the exact field encoding and timeout settings for the APISIX version in your environment against the transcoding plugin documentation before you write the test cases.

When is gRPC-Web or a direct gRPC client a better choice than transcoding?

Transcoding suits clients that expect REST and JSON, such as third-party integrations, low-code tools or teams that do not want generated gRPC stubs. A direct gRPC client is usually better when both sides are under your control, need streaming, or benefit from strongly typed stubs and binary payloads. gRPC-Web fits browser applications that must speak gRPC but cannot use native gRPC over HTTP/2, and it has its own preflight and CORS considerations. Choose by consumer type, streaming needs and the cost of maintaining JSON mappings. Review the gRPC protocol proxying options in APISIX with your architects before committing to one pattern.

What does the testing for transcoded routes need to cover?

Testing should prove that each mapped route behaves correctly for every consumer, not just that the gateway starts. A useful suite covers successful calls for each method, validation errors returned from the upstream service, authentication failures at the gateway, and the JSON shape of responses including optional and repeated fields. It should also include int64 values near the top of their range, timeouts that exceed the gateway limit, and a rerun after each proto change. Ask a partner to show how the suite is stored, who runs it in each environment, and how failures are reported to the owning team.

Who owns the transcoding configuration after the project is handed over?

Ownership should be written into the engagement before work starts. Your team typically owns the proto files, the route definitions and the test suite, because those change whenever the service contract changes. Upgrades to APISIX and any support arrangement are separate decisions that can be handled in-house or through a retainer. Ask for documentation that names each artifact, where it lives in your repository, who approves changes, and the procedure for rolling back a bad proto upload. Clear ownership prevents the common situation where the gateway mappings drift away from the service they describe.

How DeployOpen scopes and delivers APISIX gRPC transcoding

DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, so the gRPC transcoding route is built in your cloud account, data center or restricted network. Engagements are fixed-scope, with the scope, deliverables and timeline agreed in writing before work starts.

How we scope

  • Inventory which gRPC services, methods and clients need REST or browser access through the gateway.
  • Collect the proto definitions, their import paths and version ownership before any route is designed.
  • Record the written scope, including the routes, deadline rules, int64 choices and test cases agreed.

How we build

  • Configure grpc-transcode routes that map each REST path to the intended service and method.
  • Upload and validate proto descriptors in a staging APISIX instance before they reach production.
  • Test deadlines, error code mapping and int64 string handling with representative REST and browser clients.

How we hand over

  • Document the route inventory, descriptor update procedure and the owner of each proto file.
  • Provide a runbook covering descriptor changes, rollback steps and how to confirm a route is working.
  • Walk your platform and API teams through the configuration so they can extend it themselves.

How we support

  • Offer ongoing support, upgrades and continuous testing as a retainer after the handover.
  • Review descriptor and route changes when gRPC service contracts change, against the agreed scope.
  • Confirm APISIX version compatibility with your transcoding setup before any upgrade is planned.

Related

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.
Book a callhello@deployopen.com