Before meeting the product, it helps to feel the pain it removes.

What an API actually is

An API, short for application programming interface, is a set of agreed rules that lets one piece of software ask another piece of software to do something. When a mobile banking app shows your balance, it does not read the bank’s database directly. It sends a request to an API, which checks the request, fetches the balance and sends back an answer. The API is the polite, controlled doorway between two programs.

Modern systems are built from many small services instead of one giant program. One service handles orders, another handles payments, another handles product search. Each of these services may expose its own API. Over time a company may have dozens or even hundreds of them, written by different teams, in different languages, running on different platforms.

What goes wrong without a shared front door

If every team builds its own protection, the same chores are repeated again and again: checking identities, limiting traffic, recording logs, handling errors. Some teams will do them well and some will forget. A single missed check can leave a service open to the whole internet. Clients also suffer, because they must remember a different address and a different login method for each service.

A managed service that gives your backends one consistent, protected public face.

The core definition

API Gateway is a fully managed Google Cloud service that provides secure access to your backend services through a consistent REST API, no matter how each service is implemented. You describe your API in a specification file, upload it, and deploy it to a gateway. Clients then call the gateway, and the gateway forwards allowed requests to your real services. Google runs the gateway infrastructure, handles hosting, logging, monitoring and traffic management, and integrates the whole thing with the rest of Google Cloud.

The word managed matters here. You do not create virtual machines, install proxy software, patch operating systems or plan capacity for the gateway. You provide the description of your API, and Google provides the machinery that enforces it.

What it does for you

Where it sits among Google’s API tools

Google Cloud offers several products for managing APIs, and beginners often mix them up. API Gateway is the lightweight, serverless-friendly choice, aimed mainly at protecting backends such as Cloud Run services and Cloud Run functions. Cloud Endpoints is a related product where you run the proxy yourself. Apigee is a much larger platform for full API lifecycle management, developer portals and monetization. A later chapter compares them in detail.

Three words you must understand clearly, because everything else builds on them.

The three building blocks

People new to API Gateway often confuse its three main resources, because the names sound alike. Each plays a different role, and understanding the difference makes everything else easier to follow.

Why the API config is treated as a snapshot

When you upload a specification, Google creates an API config from it. You then deploy that config to a gateway. If you need to change the rules, you do not edit the live config. Instead you create a new API config and point the gateway at it. This design gives you a clear history of what was deployed, makes it easy to roll back by pointing the gateway at an older config, and avoids half-applied changes.

The gateway is regional

A gateway lives in a specific Google Cloud region and receives its own hostname under a Google-managed domain. Clients call that hostname. Because the gateway is a regional resource, you choose a region that suits your users and your backends, ideally close to both, to keep delays small.

Following one request from the client to the backend and back.

The big picture

At its heart, the gateway is a smart proxy sitting between clients and backends. A proxy is a middleman that receives a request on behalf of someone else and passes it along. The Google Cloud gateway is built on the same proxy technology family used by Cloud Endpoints, which is an Envoy-based proxy designed to work with Google’s service management and service control systems. You never see or manage that proxy, but knowing it exists explains why the features behave like those of Cloud Endpoints, including the shared authentication syntax.

flowchart LR
    A[Mobile app] --> G[API Gateway]
    B[Web app] --> G
    C[Partner system] --> G
    G --> R[Cloud Run service]
    G --> F[Cloud Run function]
    G --> E[App Engine service]
    G -.-> L[Logging and Monitoring]
        

The journey of one request

sequenceDiagram
    participant Client
    participant GW as API Gateway
    participant Backend
    participant Obs as Logging and Monitoring
    Client->>GW: Request with credential
    GW->>GW: Match path, check credential and quota
    alt Check fails
        GW-->>Client: Error response
    else Check passes
        GW->>Backend: Forward request with gateway identity
        Backend-->>GW: Response
        GW-->>Client: Response
    end
    GW->>Obs: Write logs and metrics
        

The gateway is the front desk, but real work happens in the rooms behind it.

Serverless-first design

Google’s documentation names Cloud Run functions, Cloud Run and the App Engine standard environment as options for implementing the services behind the gateway. These are all serverless platforms, meaning Google manages the servers and scales them automatically. The pairing makes sense: a managed front door for managed backends means almost nothing for your team to operate.

Backends can change without breaking clients

One of the biggest gifts of a gateway is that the public API stays stable while the backend changes. Today a path might be served by a Cloud Run function. Next year the team may rewrite it as a container and move it to Cloud Run. Clients keep calling the same address, because only the backend address inside the API config changed.

Each backend has its own door lock

A key design idea is that your backend should not be open to the whole internet. For serverless backends, you can require callers to present a valid Google identity. The gateway then uses its own service account, which is a special non-human identity, to prove who it is whenever it calls the backend. The result is a double lock: clients must satisfy the gateway, and only the gateway may satisfy the backend.

flowchart LR
    I[Internet client] -->|API key or token| G[API Gateway]
    G -->|Gateway service account identity| B[Private backend]
    I -.->|Direct call is denied| B
        

Everything the gateway knows about your API comes from one descriptive document.

What OpenAPI is

OpenAPI is a widely used standard format for describing an HTTP API in a plain text file. The file lists each path, each allowed method such as GET or POST, what inputs are accepted, what answers are returned, and how clients must authenticate. Because the format is standard, many tools can read it, from documentation generators to testing tools.

With API Gateway, this file does double duty. It documents your API, and it also configures the gateway. Google-specific extension fields inside the file tell the gateway where each operation’s backend lives, how to authenticate to it, and how quotas should work.

OpenAPI 2.0 and 3.x

API Gateway was originally built around OpenAPI 2.0, often still called Swagger. Google’s documentation describes defining a deployed API as an OpenAPI 2.0 specification that names the backend entry point, request and response formats and the authentication mechanism. More recently, support for OpenAPI 3.x has been documented as well, with its own page of feature limitations and its own set of Google extensions. Newer capabilities, such as exposing operations to AI agents through the Model Context Protocol, are described only for OpenAPI 3.0.x and 3.1.x, not for 2.0.

Features that are accepted but not enforced

This is an important detail that surprises many teams. The gateway accepts certain definitions in your file but does not actually enforce them. Documentation notes that OAuth scopes listed in security definitions are accepted but never checked. Likewise, details such as whether a parameter is required, or what format an array has, are accepted but requests are forwarded to your backend regardless. In other words, the gateway is not a full request validator. Your backend must still validate its own inputs.

Other limits worth knowing

The gateway checks credentials so your backends do not each have to.

Authentication versus authorization

Two similar words cause constant confusion. Authentication answers the question who are you. Authorization answers the question what are you allowed to do. A hotel clerk who checks your passport is authenticating you. The key card that opens only your room is authorization. The gateway is strong at the first and can contribute to the second, while fine-grained permissions inside your business logic usually remain the job of your backend.

Supported credential types

API Gateway uses the same authentication syntax as Cloud Endpoints. Documentation lists API keys, Google authentication methods using service accounts, and Google ID tokens among the options, and the OpenAPI pages also describe OAuth2-style and JSON Web Token validation through the security definitions in the specification.

How a JWT is checked

A JSON Web Token, or JWT, is a small signed package of claims, such as who issued it, who it is for and when it expires. The gateway checks that the signature is genuine using the issuer’s published public keys, that the token has not expired, and that the audience matches what the specification expects. If any check fails, the request is rejected before reaching your backend.

Combining requirements

Security rules can be combined, but the documentation lists specific restrictions. For API keys, alternatives, meaning either-or rules, that involve an API key are not supported, though requiring both an API key and an OAuth2 token together is supported. For OAuth2, either-or rules across different schemes are supported, while both-together rules across different OAuth2 schemes are not. An empty security requirement can make an API key optional, but not OAuth. These details sound fussy, yet they decide whether a design is possible, so check them early.

Protecting your backends from overload, accidents and unfair use.

Why limits matter

Even honest clients cause trouble. A bug in a mobile app might send the same request in a loop. A partner might run a huge nightly import. A single hungry client can drain capacity and slow every other customer. A quota is a promise about fairness: each caller may make only a defined number of calls in a defined period, and calls beyond that are politely refused.

How quotas work in this family of products

The gateway shares its quota model with Cloud Endpoints. You define named metrics in the specification, set limits on those metrics, and then tell each operation how much of a metric each call consumes. Heavy operations can be set to cost more than light ones. Limits are measured against the identity of the caller, which is normally derived from the API key, which is why quotas and API keys appear together so often.

Managing API keys

API keys are created and managed in your Google Cloud project, and you can restrict each key so it works only with the intended API. Documentation also notes that you can share your API through the console so other developers can enable it and generate their own keys. Good key hygiene matters: rotate keys regularly, restrict their scope, and never commit them into public code repositories.

A locked front door is useless if the back door stands open.

The gateway’s own identity

When the gateway calls a backend, it does so as a service account, a non-human identity that Google Cloud uses for programs. You choose which service account the gateway runs as, and you grant that account permission to call your backends. For example, you might give it only the permission to invoke a particular Cloud Run service, and nothing else. This is the principle of least privilege: give the smallest set of permissions that still lets the job work.

Layers of protection

Defense in depth

Security experts like layered defenses, because any single layer can have a hole. The gateway handles the outer layers well. But the gateway does not see inside your business rules, so your backend must still check whether this particular user may see this particular record. Treat the gateway as a strong outer wall, not as the only wall.

Deciding which backend answers which request, and how the address is built.

Mapping public paths to backend addresses

Each operation in your specification carries information about its backend: the address to call, and how the public path should be translated into the backend path. Two translation styles are common. In one, the public path is appended to a fixed backend address, so a call to the gateway’s orders path becomes a call to the same path on the backend. In the other, every call goes to one constant backend address, which suits single-function backends that decide what to do themselves.

One gateway, many backends

A single API config can send different paths to different backends. The orders path may go to a Cloud Run service, the reports path to a function, and an older legacy path to App Engine. To the client, it all looks like one coherent API, which is exactly the point.

flowchart TD
    C[Client] --> G[API Gateway]
    G -->|orders paths| A[Cloud Run orders service]
    G -->|reports paths| B[Cloud Run function reports]
    G -->|legacy paths| D[App Engine legacy app]
        

Timeouts and other behavior

Each backend can be given a deadline, which is how long the gateway will wait before giving up. A sensible deadline protects clients from hanging forever and protects the gateway from piling up stuck requests. Choose a deadline slightly longer than the backend’s normal worst-case time, so genuine slow calls succeed but runaway calls are cut off.

From a text file on your laptop to a live public endpoint.

flowchart LR
    S[OpenAPI file v1] --> C1[API config v1]
    S2[OpenAPI file v2] --> C2[API config v2]
    C1 --> G[Gateway]
    C2 -.->|switch when ready| G
        

Updating safely

Because configs are snapshots, you update by creating a new config and pointing the gateway at it. If something goes wrong, point the gateway back at the previous config. This gives you a simple and dependable rollback story. Name your configs with meaningful labels, such as a version number or a date, so the history is readable.

Versioning the public API

The API config version is a deployment concept. It is not the same as the version of your API as clients see it. If you need to make a change that breaks existing clients, such as removing a field, publish it under a new public path or version, and keep the old one alive until clients move. Many teams include a version label in the path, for example a prefix that marks the first or second generation of the API.

You cannot protect or improve what you cannot see.

What the gateway records

API Gateway logs information about requests and responses and tracks measurements such as latency, traffic and errors. These records flow into Google Cloud’s observability tools, where you can search logs, chart metrics and set up alerts. Because every call passes through the gateway, it is an ideal place to watch the health of your whole API surface from a single viewpoint.

Reading error codes

Status codes beginning with four usually mean the client did something wrong: a missing or invalid credential, a forbidden action, a path that does not exist, or a quota that has run out. Codes beginning with five usually mean something on the server side failed, such as a backend that is down or too slow. When errors rise, the first question is always whether they are the fours or the fives, because the fix belongs to a different team in each case.

Alerts that earn their keep

Good alerts are few and meaningful. Alert when the share of server errors passes a threshold for several minutes, when delays rise well above normal, or when traffic suddenly drops, since a sudden silence can mean clients cannot reach you at all. Avoid alerting on every single error, because constant noise trains people to ignore alarms.

The gateway is learning to speak the language of AI tools.

What the Model Context Protocol is

AI agents are programs, often powered by large language models, that can decide to call tools to get things done. To make that work smoothly, the industry created the Model Context Protocol, or MCP, a common way for agents to discover which tools exist and to call them. Normally, offering your service to agents means building and running a separate MCP server, which is extra work and extra security surface.

Turning REST operations into tools

In September 2026, Google announced a public preview that lets API Gateway act as a remote MCP server. You mark your OpenAPI 3.0.x or 3.1.x specification to enable the feature, describe each operation you want to expose with a tool name and a helpful description, and deploy as usual. The gateway then serves the MCP protocol at a dedicated path, and it translates each tool call into the matching ordinary REST request. Because the call passes through the usual machinery, your existing authentication, quotas and logging continue to apply.

sequenceDiagram
    participant Agent as AI agent
    participant GW as API Gateway
    participant API as Backend REST service
    Agent->>GW: Discover available tools
    GW-->>Agent: List of tools
    Agent->>GW: Call a tool with arguments
    GW->>API: Translate into REST request
    API-->>GW: REST response
    GW-->>Agent: Tool result
        

Points to remember

A related feature: model routing

The documentation also describes a separate model routing capability for directing traffic to AI models. It cannot be combined with the MCP feature in the same API config. Because this area is moving quickly, treat it as something to verify in the current documentation rather than assume details.

Choosing the right tool saves months of regret.

The family of Google Cloud API products

A simple way to choose

Proven ways of arranging gateways and backends.

flowchart LR
    C[Clients] --> G[API Gateway]
    G -->|new paths| N[New services]
    G -->|remaining paths| L[Legacy system]
    L -.->|shrinks over time| N
        

Anti-patterns to avoid

An honest look at strengths and limits.

Reading the trade-offs correctly

The gateway trades breadth for simplicity. It does a focused set of jobs, and does them without asking you to run anything. If your needs fit inside that set, you gain speed and calm. If your needs grow beyond it, you may eventually move some APIs to a bigger platform, and the clean separation between gateway and backend makes that move easier than it would otherwise be.

Habits that keep gateways safe, simple and dependable.

Best practices

Common mistakes

Seeing the gateway in familiar situations makes the ideas stick.

Understanding what you pay for, and what to prepare before you start.

How to think about cost

API Gateway pricing is based on usage, mainly the number of calls that pass through the gateway, and exact rates and any free allowances can change, so check the official pricing page before estimating. Remember that the gateway is only part of the bill. Your backends, such as Cloud Run services, have their own costs, and so do logging and network traffic. A fair comparison with alternatives should include the staff time saved by not running a proxy yourself.

A planning checklist

No. They share authentication syntax and related technology, but API Gateway is fully managed by Google, while with Cloud Endpoints you deploy and operate the proxy yourself.

The gateway is a pass-through layer for requests. It records logs and metrics about calls, but your application data lives in your own backends and databases.

Yes. A single API config can send different paths to different backends, such as Cloud Run services, functions or App Engine apps.

Not necessarily. Documentation says required flags and similar definitions are accepted but not enforced, so the backend must validate its own inputs.

Scopes may appear in the specification, but they are accepted without being checked. Enforce fine-grained permissions in your backend.

Point the gateway back to the previous API config. Because configs are saved snapshots, this is quick and low risk.

Usually not for sensitive data. Keys identify applications, not people, and are easy to copy. Combine them with signed tokens when identity matters.

Yes, OpenAPI 3.x support is documented along with its own limitations and extensions. Newer agent features are described only for 3.0.x and 3.1.x.

It lets the gateway expose REST operations as tools for AI agents. It was announced as a public preview in September 2026, so check current documentation and test carefully before relying on it.

Choose it when you need a full API management platform, such as developer portals, advanced policies, deep analytics or monetization, for a large API program.

A gateway is deployed in a specific region. For users spread around the world, you can deploy gateways in several regions.

Yes. Require authenticated calls on the backend and allow only the gateway’s service account, so nobody can bypass the gateway.

API Gateway in Google Cloud gives your backend services a single, well-guarded public face. You describe your API in an OpenAPI specification, store it as an API config, and deploy it to a regional gateway that checks credentials, enforces quotas, routes requests, and records everything. It pairs naturally with serverless backends, keeps your public addresses stable while the services behind them evolve, and now reaches into the world of AI agents through its preview support for exposing operations as tools. Its strength is focused simplicity, and its limits, such as unenforced parameter definitions and restricted security combinations, mean that your backends must still validate inputs and enforce business permissions. Used as a thin, well-configured outer wall, it saves effort and improves safety. Always confirm current features, limits and pricing in the official documentation before committing to a design.