Deploying REST and gRPC APIs on Google Cloud

API Management and Deployment Services are Google Cloud tools that give apps one secure, stable way to call backend services. Cloud Endpoints (opens in a new tab) manages REST and gRPC APIs through a proxy, API Gateway provides managed REST access with traffic control, and Apigee adds full lifecycle management with security and analytics. Together they let teams update or move backend code on Cloud Run, Google Kubernetes Engine (GKE), Compute Engine, or App Engine without changing the public API.

1.1API Gateway

API Gateway is a distributed API management system that provides secure access to backend services through a well-defined REST API. Traffic flows from app developers to API Gateway and then from API Gateway to backend services such as Cloud Run functions, Cloud Run, and App Engine standard environment. Because all APIs are hosted on the gateway, developers see one consistent interface even when backends use different languages, architectures, or protocols. API Gateway handles concurrent calls with built-in hosting, logging, monitoring, traffic management, and authorization, and it is natively integrated with Google Cloud. A consistent API makes services easier to consume, lets the backend be updated or moved without breaking deployed apps, and provides scaling, monitoring, and security without custom code. Choose API Gateway when multiple REST backends need one secure, managed entry point.

1.2Cloud Endpoints for REST and gRPC APIs

Cloud Endpoints is the service for developing, deploying, and managing APIs on Google Cloud for both OpenAPI REST and gRPC protocols. For gRPC, development follows an ordered workflow where each step depends on the previous one:

1. Define service: Define the gRPC API service using protocol buffers and implement it in any gRPC-supported language.
2. Write configuration: Write the gRPC API service configuration for Endpoints.
3. Deploy configuration: Generate the runtime API configuration and deploy it to Service Management.
4. Deploy server: Deploy the API server code to the chosen compute platform.

Endpoints also controls who can call an API by requiring and validating an API key for calls. An API can be shared through the Google Cloud console so other developers can enable it and generate their own keys. API keys identify which app is calling, while authentication determines which user is using that app, and the backend server still decides what that authenticated user is allowed to do.

1.3Deploying Endpoints Backends With ESP and ESPv2

The Extensible Service Proxy (ESP) is the proxy that sits in front of API backend code so Endpoints can manage traffic. The proxy depends on two inputs: the service name and an option that points it to the latest deployed Endpoints service configuration. With that information, ESP fetches the configuration and then proxies requests to the API backend (opens in a new tab) and responses back to clients, applying management, logging, and access checks in the path. ESP and Extensible Service Proxy V2 (ESPv2) (opens in a new tab) have different environment support, and deployment steps vary by platform. On the App Engine flexible environment, deployment is nearly the same as any App Engine deployment with a small Endpoints configuration addition, using gcloud app deploy to build a container and deploy it. On Compute Engine, Docker must be installed on the virtual machine (VM) instance to run the ESP Docker image from Artifact Registry alongside a container for the backend code. On GKE, clusters created in the console grant the service account the OAuth scopes Endpoints requires by default.

1.4Apigee and API Proxies as a Facade

Apigee is Google Cloud's native API management solution for developing, securing, deploying, and monitoring APIs. Apigee Hybrid (opens in a new tab) extends the same model to on-premises environments, edge, other clouds, and Google Cloud. A central idea in Apigee is the cloud-managed API proxy, which decouples the app-facing API from backend services such as microservices. Traffic flows from client apps to the Apigee proxy and then from the proxy to the backend, so backend code can change without forcing apps to change. Deploying a gateway or proxy as a unifying facade overcomes inconsistencies in protocols, APIs, and authentication across diverse backend services (opens in a new tab). The facade acts as a centralized control point that:

• Implements additional security measures across backends.
• Shields client apps and other services from backend code changes.
• Facilitates audit trails for communication between cross-environment apps and decoupled components.
• Acts as an intermediate communication layer between legacy and modernized services.

Apigee proxies also support existing API-driven frontend patterns such as backend for frontend (BFF) and microfrontend. Apigee adds rate limiting, quotas, and analytics on top of the proxy layer. Choose Apigee when APIs need enterprise-grade control, exposure to internal and external consumers, and operation across hybrid environments.

1.5Scaling and Securing APIs With Load Balancing

Combining an API gateway or proxy with an Application Load Balancer provides a more robust solution for managing, securing, and distributing API traffic at scale. Traffic flows from clients to Cloud Load Balancing and then to API gateways in one or more regions, which then forward to backends on Cloud Run, GKE, Compute Engine, or on-premises through hybrid connectivity. This pairing enables advanced traffic management and efficient balancing across gateways in multiple regions. The combined design also improves performance and protection for external and internal traffic. Apigee paired with Cloud CDN reduces latency, hosts APIs globally, and increases availability during peak traffic, while Cloud Armor adds distributed denial-of-service (DDoS) and application-layer protection when APIs are exposed externally. For service-to-service communication inside a microservices system, Cloud Service Mesh manages authentication, authorization, and encryption to maintain quality of service, while Apigee exposes selected services outward as managed APIs. The three management options differ in protocol support, backend integration, and control:

Architectural Design and Protocol Selection is the choice between HTTP REST and gRPC for how clients and services exchange data. HTTP REST uses resource-oriented URLs and standard HTTP verbs with JSON payloads, while gRPC uses defined remote procedure call (RPC) methods with structured request and response messages. The contract for REST is described by a machine-readable Discovery document, while the contract for gRPC is described by service, method, and message definitions.

2.1REST Service Contracts With Discovery Documents

The Google APIs Discovery Service (opens in a new tab) defines REST contracts through two concepts: the APIs Directory and the Discovery document. The APIs Directory is a list of supported APIs where each entry provides name, version, title, description, documentation link, status labels, and the full URL of its Discovery document. The Discovery document is a machine-readable description of one API version that describes how to access its methods through RESTful HTTP calls. A Discovery document for a REST API groups data objects called resources under a top-level resources section, with methods nested under each resource and optionally at the API level. The document also contains a top-level schemas section based on JSON Schema draft-03, an auth section that defines OAuth scopes, and inline documentation for schemas, methods, parameters, and parameter values. Schemas can reference other schemas with $ref, and methods reference schemas to define their request and response bodies, so a client library can model objects directly from the contract. REST operations from the Discovery Service map directly to HTTP verbs and URIs. The list operation maps to GET on the Directory resource URI, such as GET https://discovery.googleapis.com/discovery/v1/apis, and a specific API description is retrieved with GET https://API/$discovery/rest?version=VERSION. For example, data flows from the Service Usage API server to the client in response to GET https://serviceusage.googleapis.com/$discovery/rest?version=v1. This pattern makes REST contracts discoverable by any HTTP client without generated stubs.

2.2gRPC Service Contracts With RPC Methods

The FoodOrderingService defines its gRPC contract through named RPC methods and strongly typed messages exchanged between a client application and the agent. The service exposes FoodOrderingService.BidiProcessOrder for real-time interaction and FoodOrderingService.ProcessOrder for turn-based interaction, each with its own request and response message types. Every session must begin with client-provided configuration in a Config message that carries the store, session identifier, and mode. The Config message controls how the session depends on backend configuration and identity. The store field carries the full resource name projects/PROJECT/locations/LOCATION/brands/BRAND/stores/STORE, and the session inherits configuration from the referenced Store resource and its parent Brand resource, where Store configuration takes precedence on conflict. The session field carries a client-generated identifier in the format projects/PROJECT/locations/LOCATION/sessions/SESSION that uniquely identifies one customer conversation. The mode field selects HYBRID for voice and text or TEXT for text only, which determines which RPC pattern the session can use.

2.3Unary and Bidirectional Streaming Patterns

Unary and bidirectional streaming patterns are the two ways the FoodOrderingService exchanges order data over gRPC and REST. The ProcessOrder pattern is unary request-response for discrete, text-based turns, where the client sends one ProcessOrder request and the agent returns one response. The method is also accessible as POST /v1/{config.session=projects/*/locations/*/sessions/*}:processOrder, where the session identifier from Config flows from the client to the server in the URL path. Unlike streaming, each turn is separate and text-only, so the client must manage conversation progress explicitly. The turn lifecycle for ProcessOrder moves through ordered states defined by turn_type and mode. First, the client sends an INITIALIZE turn to inject session variables such as menu and store metadata, with config.mode explicitly set to TEXT. Then, the client sends follow-up turns with turn_type set to SUBSEQUENT to continue the same session. Because the mode requirement is strict for unary REST access, a missing or non-TEXT mode prevents the turn from being processed as intended. The BidiProcessOrder pattern is bidirectional streaming where data flows concurrently in both directions over one long-lived connection. Data flows from the client application to the agent as a stream of BidiProcessOrderRequest messages containing audio input, text input, or event inputs such as a client-side cart update or a hardware-detected drive-off event. Data flows from the agent to the client as a stream of BidiProcessOrderResponse messages containing synthesized audio output, text output, transcripts of recognized speech, updates to order state, or signals such as detected interruptions. For BidiProcessOrder, mode is optional and defaults to HYBRID, which enables low-latency, real-time multimodal interaction without a separate request per turn. Session resumption depends on the session identifier supplied in the initial Config message. If a client disconnects due to network issues and reconnects to BidiProcessOrder with the same session identifier, the agent resumes the session from its previous state. If the client supplies a new session identifier, the API initiates a new ordering session instead of continuing the old conversation.

2.4Selecting Between REST Unary and gRPC Streaming

Selection between REST unary and gRPC streaming depends on client capability, latency needs, and input modality rather than on preference alone. Unary REST with ProcessOrder fits browser widgets and integrations that can only send HTTP POST with JSON text and need simple turn-by-turn logic. Bidirectional gRPC with BidiProcessOrder fits voice-driven clients that need concurrent audio in both directions and immediate feedback such as transcripts and interruption signals. The two methods differ in access, interaction style, and supported inputs:

Security, Authentication, and Operational Reliability for APIs is the practice of protecting API traffic and access while keeping distributed services observable and available. In Google Distributed Cloud (GDC) air-gapped, control-plane APIs are built on Kubernetes using the Kubernetes Resource Model (KRM) for creation, deletion, and updates, while service data-plane APIs use XML, JSON, or gRPC. Most APIs (opens in a new tab) offer a JSON HTTP interface, Kubernetes-based APIs use Kubernetes client libraries, and some non-Kubernetes APIs also offer a gRPC interface for improved performance and usability.

3.1Securing API Traffic With Encryption

Transport Layer Security (TLS) is the encryption layer that protects all GDC API requests in transit between clients and API servers. When traffic flows from a Kubernetes or GDC client library to the API server, the library handles in-transit encryption automatically. When traffic flows from a custom HTTP or gRPC client to the API server, the client owner must implement TLS and authentication, including following the gRPC authentication guide for gRPC. Use existing clients, especially ones Google provides, for exploration and one-off work with the gdcloud CLI tools or GDC console. Use the GDC APIs (opens in a new tab) directly only for automated or programmatic access, because an incorrect custom client can cause behaviors that are difficult to diagnose.

3.2Authentication and Restricted API Access

Authentication for Kubernetes-based APIs is the process where a client proves its identity with cluster location information and credentials before the API server allows CRUD operations on resources. The kubectl command-line tool is the primary way to work directly with the Kubernetes API, and kubectl config view shows the clusters the current configuration can access. Running kubectl proxy starts a reverse proxy that connects to the apiserver, manages authentication, and verifies the API server identity with a certificate, which guards the client-to-server trust boundary against man-in-the-middle attacks. System APIs used by the underlying GDC system are discoverable with kubectl and open source tools, but access to those APIs is restricted to the relevant Infrastructure Operators. Developers work through Service APIs (opens in a new tab) and the zonal or global management endpoints, so system controls stay separated from developer access.

3.3Choosing Global and Zonal APIs for Fault Tolerance

Global and zonal APIs are the two management-plane levels that create and manage GDC resources represented as Kubernetes custom resources at different endpoints. Zonal resources operate independently within a single zone, so a zonal outage can affect some or all resources in that zone, while global resources operate with redundancy across multiple zones for fault tolerance. The global API servers share a single etcd cluster distributed across zones to provide strong consistency with fault tolerance, at the cost of higher latency and reduced write queries per second (QPS) compared to the zonal API servers. The choice is a tradeoff between resilience and performance:

3.4Monitoring for Observability Across Distributed Services

Cloud Monitoring is Google Cloud's integrated monitoring tool that ingests events, metrics, and metadata and exposes insights through dashboards and alerts. Metrics flow from Google Cloud services, third-party sources, and OpenTelemetry-instrumented apps into Cloud Monitoring, and from there to dashboards, alerts, and autoscaling controls. Cloud Monitoring can also serve as the backend for popular open source monitoring tools to provide a single pane of glass. Monitoring at all levels gives a holistic picture of health because infrastructure signals alone cannot reveal broken workflows or service-to-service latency:

• Infrastructure monitoring captures baseline health from CPU load, memory usage, and bytes written to disk, plus detailed Compute Engine VM and third-party app data collected by the monitoring agent.
• App monitoring captures developer-defined workflow signals, such as query time or sequences of service calls, collected and exported with OpenTelemetry.
• Service monitoring captures interactions between microservices, such as errors and latency between components, observed and secured with Cloud Service Mesh on and off Google Cloud.
• End-to-end monitoring tests externally visible behavior the way a user sees it, checking whether critical actions complete within defined thresholds to reveal availability as perceived by the user.

App-level and service-level metrics complement infrastructure metrics because aggregated workflow conditions reveal problems that low-level machine signals do not.

3.5Exposing Health for High Availability

Health checking is the pull-based pattern where a checker requests data from an endpoint to decide whether a service should receive traffic. Load-balancer health checks define how the load balancer communicates with virtual machine instances to evaluate whether particular instances should continue to receive traffic, and the same checks can autoheal managed instance groups by recreating unhealthy machines. When external traffic is load-balanced through an ingress resource on GKE, GKE automatically creates the appropriate health checks for the load balancer. Kubernetes liveness and readiness probes help the Kubernetes orchestrator decide how to manage pods and requests within the cluster, so unhealthy pods stop receiving requests while the system reconciles desired state with real state. Together, load-balancer checks and Kubernetes probes keep traffic flowing only to healthy instances, which supports scalable and resilient apps (opens in a new tab).

Key Facts

• API Gateway provides managed REST access, Cloud Endpoints manages REST and gRPC APIs through ESP or ESPv2, and Apigee exposes backends through API proxies that decouple apps from backend changes.
• ESP is only supported on the App Engine flexible environment, while ESPv2 can be deployed on GKE and Kubernetes but does not support App Engine.
• ProcessOrder is unary text-only interaction that requires mode TEXT with INITIALIZE then SUBSEQUENT turns, while BidiProcessOrder is bidirectional streaming that defaults to HYBRID mode.
• Global APIs provide multi-zone redundancy with higher latency and reduced write QPS, while zonal APIs provide lower latency and higher write QPS without cross-zone redundancy.