API Gateway is a managed Google Cloud service that sits in front of your backend services, gives them a single public address, and applies rules about who may call them and how often.

Let us start with the word API. It stands for Application Programming Interface. In simple terms, an API is a menu of requests that one program can make to another. A weather service might offer an API where you ask, “What is the temperature in Delhi?” and it answers with a number. Most web APIs use the same language as web pages, called HTTP, and often exchange information in a tidy text format called JSON. Each kind of request has an address, called an endpoint, such as “/orders” or “/users/42”.

A gateway is a doorway. An API gateway is a doorway that all API requests must pass through before reaching the programs behind it. Those programs are called the backends, which means the services that do the real work. Google Cloud API Gateway is designed to front backends that run on serverless Google Cloud services, such as Cloud Functions, Cloud Run, and App Engine. Serverless means you do not manage servers yourself. You provide code, and Google runs it and scales it for you.

You describe your API in a document written in a standard format called OpenAPI. You give that document to API Gateway, create a gateway, and the service gives you a public web address. Clients call that address. The gateway checks their identity, applies limits, forwards the call to the correct backend, and returns the reply.

What it does for you

Gateways exist because exposing many small services directly to the internet quickly becomes messy and risky.

In the old days, a company often built one large program, called a monolith, that did everything. It had one address, and security rules lived inside it. Over time, teams split large programs into many small services, called microservices, so they could be built and updated independently. This was great for speed, but it created a new puzzle: how do outsiders reach all those services?

One option is to let every service face the internet by itself. Then every team must build its own login checks, its own traffic limits, its own logging, and its own security fixes. Mistakes multiply. A forgotten check in one small service becomes a hole in the whole company. Clients also need to know a dozen addresses, and any change in the layout breaks them.

The API gateway pattern solves this by putting one shared layer in front. Common rules are written once and applied to every request. Services behind it can be simpler, because they can assume that the gateway already handled the basics. The pattern became very popular, and many products appeared, from open-source proxies to large commercial platforms.

Google Cloud offered several answers over time. An earlier product, Cloud Endpoints, used a proxy that you ran yourself next to your service. A fuller, enterprise-grade platform, Apigee, covers the entire life of APIs, including developer portals and analytics. API Gateway arrived as a simpler, fully managed option for serverless backends, built on the same proxy technology as Endpoints but without the need to run the proxy. How these products are positioned can evolve, so check the current documentation and product pages when choosing.

The pains it removes

Three main objects and a few helper ideas explain almost everything you will see in the console.

API

In Google Cloud API Gateway, an API is a named container. It represents one logical API, such as “orders-api”. By itself it holds no rules. It is a folder in which versions of your API definition are stored.

API config

An API config is a saved snapshot of your API’s rules. It is created from your OpenAPI document and describes the paths, methods, security checks, quotas, and which backend to call for each path. Once created, an API config does not change. If you want to change a rule, you create a new API config. This makes rollbacks safe: the old snapshot still exists.

Gateway

A gateway is the running doorway. It is created in a specific region, and it is attached to exactly one API config at a time. The gateway receives a public web address. When you want to publish a change, you update the gateway to use a newer API config. To roll back, you point it at an older one.

Backend

A backend is the service that does the real work, such as a Cloud Function, a Cloud Run service, or an App Engine app. Your API config tells the gateway the address of each backend.

OpenAPI document

The OpenAPI document is a structured text file in a widely used standard. It lists your paths and operations, the shape of requests and responses, the security methods, and Google-specific extensions that tell the gateway where to send calls. The gateway’s current support is for a particular version of the standard, so check the documentation for the exact version it accepts.

Supporting ideas

• API key: a long random string that identifies a calling project or application.
• JWT: a signed digital token, short for JSON Web Token, that proves who the caller is and carries facts about them.
• Service account: an identity for a program, not a person. The gateway uses one to call your backends.
• Quota: a limit on how many calls may be made within a period.
• Managed service: the behind-the-scenes object that Google creates from an API config to enforce checks and collect data.

Before diving into details, it helps to see the overall picture: who talks to the gateway, what it talks to, and what it replaces.

The overall picture

Clients, such as mobile apps, websites, partner systems, and other services, send requests over the internet. All of them are directed to the gateway’s address. The gateway checks and forwards each request to the correct backend, then returns the response. The backends in turn may talk to databases, queues, and other services, which are not visible to the outside world.

flowchart LR
  Mob["Mobile app"] --> GW["API Gateway: one public address"]
  Web["Website"] --> GW
  Par["Partner system"] --> GW
  GW -->|"/orders"| CF["Cloud Function: orders"]
  GW -->|"/payments"| CR["Cloud Run: payments"]
  GW -->|"/profile"| AE["App Engine: profiles"]
  CF --> DB[("Database")]
  CR --> DB
  AE --> DB
    

What a gateway is not

A gateway is easy to confuse with other tools. A load balancer spreads traffic across copies of the same service. A gateway chooses between different services and applies rules about callers. A reverse proxy forwards requests on behalf of servers, and a gateway is a special kind of reverse proxy with API-aware rules. A firewall blocks network traffic by addresses and ports, while a gateway understands the meaning of API requests. A service mesh manages traffic between internal services, and a gateway manages traffic between the outside world and those services.

API Gateway is made of a control side, where you manage your APIs, and a data side, where real requests flow. Seeing the split makes the product much easier to understand.

Google does not publish every internal detail of how its managed services are built, which is normal. What we can describe with confidence is the conceptual architecture, based on how Google describes the product: a control plane for your configuration, and a data plane that handles live traffic using a proxy built on well-known open-source technology. Treat this chapter as a mental model, not a blueprint of Google’s internals.

The control plane

The control plane is where you create APIs, upload configs, and create gateways. It stores your configuration and tells the data plane what to enforce. You reach it through the Google Cloud console, the command line, or the programming interface. Behind the scenes, it relies on service management features that turn your OpenAPI document into rules, and on identity and access management to decide who may change them.

The data plane

The data plane is the running gateway. Google describes it as being based on a proxy called Envoy, adapted into a component known as the Extensible Service Proxy. For every request, the proxy consults the rules, asks a checking service whether the caller and the request are allowed, applies quotas, forwards the call to the backend, and later reports what happened for logging and metrics.

Supporting services

flowchart TD
  Adm["Administrator: console, CLI, or API"] --> CP["Control Plane: APIs, configs, gateways"]
  CP --> SM["Service Management: builds managed service from config"]
  SM --> DP["Data Plane: gateway proxy in chosen region"]
  Cl["Client request"] --> DP
  DP --> SC["Service Control: check key, quota, and report usage"]
  DP --> JW["Token validation using provider public keys"]
  DP --> BE["Backend: Function, Cloud Run, or App Engine"]
  BE --> DP
  DP --> Cl
  DP --> OBS["Cloud Logging, Monitoring, and Trace"]
  IAM["IAM and service account"] --> CP
  IAM --> BE
    

Regions

A gateway is created in a particular geographic region, and the set of supported regions is limited and may grow. Choose a region near your users and your backends to reduce delay, and confirm the current list in the documentation.

Every request follows the same short journey. Knowing the order of checks explains almost every error message you will meet.

Step by step

sequenceDiagram
  participant C as Client
  participant G as API Gateway
  participant S as Service Control
  participant B as Backend
  participant L as Logs and Metrics
  C->>G: GET /orders/42 with API key or token
  G->>G: Match path and method to config
  G->>G: Validate token signature, issuer, audience, expiry
  G->>S: Check API key and quota
  S-->>G: Allowed
  G->>B: Forward request with gateway identity token
  B-->>G: Response with order data
  G->>S: Report usage
  G->>L: Write log entry and metrics
  G-->>C: Response
    

Why the order matters

The gateway rejects bad requests as early as possible. This is both a safety feature and a cost saver. A request without a valid key never wakes up a function and never costs backend time. Attackers who flood the gateway with junk are stopped at the door, not inside the building. This is also why backend logs may look quiet while the gateway logs show many rejected calls: the rejection happened before the backend was involved.

The OpenAPI document is the single source of truth for your gateway. Understanding what goes in it, in plain words, is the most useful skill for working with the service.

OpenAPI is a widely used standard for describing web APIs in a text file. Because it is a standard, many other tools can read it: documentation generators, testing tools, and code generators. API Gateway reads your OpenAPI document to create its rules. This chapter describes the parts of the document in words, without code, so you can follow the idea. The exact version of the standard that the gateway accepts, and the exact names of Google-specific extensions, are listed in Google’s documentation.

The main sections

The backend hint

The most important extension tells the gateway where to send calls. It can be set for the whole API or for individual operations. It names the backend address, which may be the web address of a function or a Cloud Run service. It also sets how the path is rewritten when forwarded, and the time limit for the backend to respond. Path handling has two common styles: either the gateway sends all calls to a fixed backend address, or it adds the incoming path to the backend address. Choosing the right style matters because the wrong one makes a perfectly healthy backend look broken.

Security definitions

Security definitions describe the methods that callers may use to prove themselves: an API key sent in a header or query string, or a signed token from a named issuer, with details of where to find the issuer’s public keys and which audience value to expect. Each operation can then state which definitions apply. An operation with no security requirement is open to everyone, so every open operation should be a deliberate decision.

Quota definitions

The document can define named metrics that count calls, and limits that say how many calls are allowed per time period, usually per project. Operations are then linked to a metric with a cost, so some operations can consume more of the allowance than others. This allows you to treat a heavy search call as more expensive than a simple lookup.

flowchart TD
  Doc["OpenAPI Document"] --> Info["Info: title and version"]
  Doc --> Paths["Paths and operations"]
  Doc --> Sec["Security definitions: keys and tokens"]
  Doc --> Ext["Google extensions"]
  Paths --> Op1["GET orders: requires key"]
  Paths --> Op2["POST orders: requires token"]
  Ext --> BE["Backend address, path style, timeout"]
  Ext --> Q["Quota metrics and limits"]
  Op1 --> BE
  Op2 --> BE
  Sec --> Op1
  Sec --> Op2
    

The gateway is only as useful as what stands behind it. This chapter explains the backends it commonly fronts and how calls reach them.

Cloud Functions

Cloud Functions runs small pieces of code, called functions, in response to requests or events. You write a function that takes a request and returns a response, and Google handles the servers and scaling. It is ideal for small, focused operations such as “look up an order” or “send a confirmation”. Functions may need a moment to start if they have been idle, which is called a cold start. Cold starts can add delay to the first request after a quiet period.

Cloud Run

Cloud Run runs containers, which are neat packages that hold a program and everything it needs. You can use almost any language or framework, and Cloud Run scales the number of running copies up and down automatically, even down to zero when there is no traffic. It suits larger services and teams that already package their programs as containers.

App Engine

App Engine is an older platform for hosting web applications with automatic scaling. Many companies still run important applications there, and the gateway can sit in front of them.

Mixing backends behind one gateway

One of the gateway’s real strengths is that one API can send different paths to different backend types. A company may keep a few legacy paths on App Engine, new features on Cloud Run, and tiny helper operations on Functions, and present them all to clients as one seamless API. This allows gradual modernization: you can move a path from one backend to another by changing the config, and clients never notice.

flowchart LR
  GW["API Gateway"] -->|"/legacy/reports"| AE["App Engine app"]
  GW -->|"/orders"| CR["Cloud Run service"]
  GW -->|"/notify"| CF["Cloud Function"]
  CR --> DB1[("Orders database")]
  CF --> Q["Message queue"]
  AE --> DB2[("Legacy database")]
    

Timeouts and deadlines

Each backend call has a time limit. If the backend is slower than the limit, the gateway gives up and returns an error. You set the limit per operation. Pick a value that fits what the operation truly needs. A very short limit causes false failures on slow days. A very long one ties up resources and lets slow calls pile up. Also remember that the gateway has its own maximum limits, which may differ from those of the backend, so check the documentation for current values.

Backends that are not covered

The gateway is designed around Google Cloud serverless backends reachable through web addresses. Backends that live only inside a private network, on virtual machines with no public front, or in other clouds may not be reachable directly. Teams in that situation often put another layer in between, such as a load balancer or a proxy service, or choose a different gateway product. Check the current capabilities for your exact case.

Authentication means checking that callers are who they say they are. The gateway supports several methods, each suited to different callers.

API keys

An API key is a long secret string that identifies the calling project or application. The caller adds it to each request. The gateway checks that the key is valid and belongs to a project that has permission to use the API. Keys are simple and popular for public data and for tracking usage per partner. But a key is only a shared secret: anyone who steals it can pretend to be the owner. Keys also identify applications, not individual human users. Use them for identification and quota control, and do not treat them as strong proof of a person’s identity.

JSON Web Tokens

A JSON Web Token, or JWT, is a digitally signed message created by an identity provider after a user signs in. It contains facts such as who the user is, who issued the token, who it is intended for, and when it expires. The gateway can verify the token’s signature using the provider’s public keys, without calling the provider on every request. If the signature is valid and the facts match the expected values, the request proceeds. This method is stronger than an API key for identifying individual users, because tokens are short-lived and tied to a sign-in event.

The gateway can validate tokens from several kinds of providers, including Google sign-in, Firebase Authentication, and other providers that follow the same open standard, such as Auth0 or Okta. You configure the issuer name, the audience value your API expects, and where to find the public keys.

Service account tokens

When one program calls another, there is no human to sign in. Instead, the caller uses a service account, an identity for programs, and obtains a signed token for it. The gateway can be configured to accept tokens from specific service accounts, which makes it suitable for protecting internal or partner machine-to-machine calls.

Combining methods

Many APIs use more than one method together. For instance, a key identifies the calling application for quota purposes, while a token identifies the user. An operation can require either of several methods or all of them, depending on how the document is written. Decide per operation what it truly needs.

flowchart TD
  R["Incoming request"] --> K{"Operation needs API key?"}
  K -->|"Yes"| KC["Validate key and project"]
  K -->|"No"| T
  KC -->|"Invalid"| X1["Reject: 401 or 403"]
  KC -->|"Valid"| T{"Operation needs token?"}
  T -->|"Yes"| TC["Validate signature, issuer, audience, expiry"]
  T -->|"No"| OK["Continue to quota check"]
  TC -->|"Invalid"| X2["Reject: 401"]
  TC -->|"Valid"| OK
    

Checking identity is only half the job. Systems must also decide what each identity may do, and make sure nobody can slip around the gateway to hit the backends directly.

Authentication versus authorization

Authentication asks, “Who are you?” Authorization asks, “Are you allowed to do this?” The gateway handles the first well and can handle some of the second, such as requiring a certain audience or scope. Fine-grained decisions, such as “this user may only see their own orders”, usually need the business knowledge that lives in the backend. A good design splits the work: the gateway rejects clearly invalid callers, and the backend enforces rules about the data itself.

The gateway’s own identity

When the gateway forwards a request, it acts as a particular service account, which you choose when you create the gateway. The gateway attaches a signed token for that account to the call. The backend can be set so that it accepts only calls carrying a valid token from this account. To make that work, you grant that service account permission to invoke the backend, using the invoker role of the relevant service.

Closing the side doors

A very common mistake is to leave the backend open to the world. Then an attacker simply ignores the gateway and calls the function or service directly, bypassing keys, tokens, and quotas. The correct design is to require authentication on every backend and allow only the gateway’s service account to invoke it. Some platforms also let you limit which network paths may reach a backend, and you should use those controls where they are available and appropriate.

flowchart TD
  Atk["Attacker"] -->|"Direct call to backend"| BE["Backend requires authenticated invoker"]
  BE -->|"No valid token"| Den["Rejected"]
  Cl["Legitimate client"] --> GW["API Gateway"]
  GW -->|"Call with gateway service account token"| BE
  BE -->|"Invoker permission granted to gateway account only"| OK["Request served"]
    

Passing identity information along

Once the gateway has verified a user’s token, the backend often wants to know who the user was. The gateway can pass the verified information onward, typically in a header, so the backend can apply rules such as “this user may only view their own records”. Backends should rely on information the gateway has verified, and should never trust identity claims that come from the client without verification. Check the documentation for exactly how verified identity data is forwarded.

Least privilege everywhere

Even honest callers can send too much traffic by accident, and dishonest ones do it on purpose. Limits protect your backends and your budget.

Why limits matter

Serverless backends scale up automatically when traffic grows. That is wonderful for real customers but dangerous against abuse, because the service will happily scale up, and charge you, to answer a flood of junk requests. A quota is a limit on how many calls may be made in a period, such as a minute. When the limit is reached, further calls receive an error until the period resets. Quotas turn a potentially unlimited bill into a bounded one.

How quotas work in the gateway

In your API definition, you declare named metrics that count requests, and limits that set the allowed amount per time period, typically counted per project, which in practice means per API key owner. Operations are linked to metrics, and each call consumes a chosen cost. The gateway asks the checking service on every request whether quota remains and returns a “too many requests” response when it does not. Details such as available time windows and how precisely counts are enforced are in the documentation. In particular, counting across a distributed system is approximate, so treat limits as strong guard rails, not as exact accounting.

Different limits for different callers

Because quotas are tied to the calling project, you can offer different tiers. A free partner may be allowed a small number of calls per minute, while a paying partner gets more. To do this in practice, you give each partner a separate project and key and adjust their quota. How flexible the per-consumer controls are depends on the product, which is one reason larger programmes look at fuller API platforms.

Other protections

• Request size limits: the gateway and backends enforce maximum body sizes. Keep your limits as small as your use case allows.
• Timeouts: stop slow calls from tying up capacity.
• Backend scaling caps: set a maximum number of instances on the backend as a final safety net against runaway cost.
• Web application firewall: for protection against common web attacks and large floods, many companies place a load balancer with a protection service in front of the gateway. Check current documentation for supported combinations.
• Budgets and alerts: set billing alerts so unexpected growth is noticed quickly.

flowchart LR
  Fl["Traffic flood or heavy partner"] --> WAF["Optional: load balancer with web protection"]
  WAF --> GW["API Gateway"]
  GW --> Q{"Quota remaining?"}
  Q -->|"Yes"| BE["Backend with max instance cap"]
  Q -->|"No"| R429["Return 429 Too Many Requests"]
  BE --> Bill["Bounded cost"]
    

Changing a live API without breaking its callers is an art. The separation of API configs and gateways is the tool that makes it safe.

How a change reaches production

flowchart LR
  Git["OpenAPI file in Git"] --> C1["API Config v1"]
  Git --> C2["API Config v2"]
  C1 --> GS["Staging Gateway"]
  C2 --> GS
  C1 --> GP["Production Gateway"]
  C2 -.->|"promote after tests"| GP
  GP -.->|"rollback"| C1
    

Versioning your public API

There is a difference between the config version (your internal snapshot) and the API version that callers see, such as “v1” or “v2” in the address. Callers depend on the shape of requests and replies. If you must change them in a way that breaks old callers, publish a new version of the API alongside the old one, for example under a new path prefix, and give callers time to move. Retire the old version only after usage drops and callers have been notified.

Safe change patterns

• Additive changes first: adding a new optional field or a new path rarely breaks callers.
• Avoid removing or renaming: these break callers and need a new version.
• Run old and new together: keep both versions live during migration.
• Announce deprecations: tell callers early, repeat reminders, and show dates in documentation and, if possible, in response hints.

Every gateway gets a default address, but companies usually want their own name on it. Here is how addresses, encryption, and network paths fit together.

The default address

When you create a gateway, Google assigns a default web address that ends in a Google-owned domain and includes a generated name. It works immediately and is protected by encrypted connections. It is perfectly good for testing and for internal use, but it is not pretty and cannot be changed.

Your own domain name

For a public product, clients should call something like “api.yourcompany.com”. At the time of writing, the common way to achieve this has been to place a Google Cloud load balancer in front of the gateway, using a special backend type that targets serverless services, and to attach your domain and a security certificate to the load balancer. This gives you extra benefits as well: you can add web protection, use a stable global address, and combine several gateways or backends behind one name. Google may offer more direct options over time, so check the current documentation.

Encryption in transit

Traffic between clients and the gateway is encrypted using the standard secure web protocol, often called HTTPS. This prevents eavesdroppers from reading or changing messages on the way. Between the gateway and backends hosted on Google Cloud, traffic is also sent over encrypted connections. Always require secure connections and never allow plain, unencrypted access to an API that carries any private information.

Regions and delay

Distance adds delay. If your users are mostly in India and your gateway is in a faraway region, every call pays that extra travel time. Choose a gateway region close to your main users, and place backends in the same region where possible so the gateway does not cross oceans to reach them. If you serve several parts of the world, you may run several gateways, one in each region, and use a global load balancer to direct users to the nearest one.

flowchart TD
  U1["Users in Asia"] --> LB["Global load balancer with your domain and certificate"]
  U2["Users in Europe"] --> LB
  LB --> W["Optional web protection policy"]
  W --> G1["Gateway in Asia region"]
  W --> G2["Gateway in Europe region"]
  G1 --> B1["Backends in Asia region"]
  G2 --> B2["Backends in Europe region"]
    

You cannot protect or improve an API you cannot see. The gateway provides a rich stream of records and measurements.

Logs

Each request produces a log entry, which is a time-stamped record of what happened: the path, the method, the response code, the delay, the size, and often which key or caller was involved. Logs go to Cloud Logging, where you can search and filter them. They answer questions like “Which calls failed in the last hour?” or “Who is calling this deprecated path?” Be careful not to log sensitive personal data, and set sensible retention periods.

Metrics

Metrics are numbers measured over time, shown as charts in Cloud Monitoring. Important ones include request count, error count by status class, and latency, which is the time to answer. A useful summary is called the four golden signals: traffic, errors, latency, and saturation, which means how close you are to a limit. Watching these four tells you most of what you need to know about health.

Tracing

A trace follows one request through the gateway and backend, showing where time was spent. If a call takes two seconds, a trace shows whether the gateway, the function startup, or a slow database was to blame. Tracing is invaluable for finding the slowest link.

Alerts worth setting

flowchart TD
  Req["Every request"] --> Log["Log entry in Cloud Logging"]
  Req --> Met["Metrics: traffic, errors, latency"]
  Req --> Trc["Trace spans through backend"]
  Log --> Q1["Search and investigate"]
  Met --> Dash["Dashboards and SLO tracking"]
  Met --> Al["Alerts to on-call"]
  Trc --> Slow["Find the slowest step"]
  Al --> Resp["Respond and fix"]
    

A gateway is a security checkpoint, but it is not a magic shield. This chapter shows which risks it reduces and which remain your responsibility.

Common API risks

The security community maintains a well-known list of the most frequent API weaknesses. Several of them matter directly for gateway designs.

Handling secrets

Secrets such as signing keys, passwords, and client credentials must never be written into the OpenAPI document, which is stored and often shared widely. Keep them in a dedicated secret store and let backends fetch them at runtime. Rotate them on a schedule and immediately after any suspected leak.

Cross-origin rules

Web browsers block a page from one site from calling an API on another site unless the API explicitly allows it. This protection is called cross-origin resource sharing, or CORS. If you build a website that calls your API from a different domain, you must configure the allowed origins and methods correctly. Be as specific as possible: allowing every origin may be fine for fully public data, but it is risky for anything personal.

Input validation

Never trust data from callers. Validate sizes, types, and allowed values. The OpenAPI document describes the expected shapes, but a gateway may not enforce every detail, so validate again inside the backend. Treat all input as potentially hostile, including headers and query strings.

Defense in depth

flowchart TD
  L1["Layer 1: Edge protection and rate controls"] --> L2["Layer 2: Gateway authentication and quotas"]
  L2 --> L3["Layer 3: Backend only accepts the gateway identity"]
  L3 --> L4["Layer 4: Backend authorizes each record"]
  L4 --> L5["Layer 5: Data store permissions and encryption"]
  L5 --> L6["Layer 6: Logging, alerts, and review"]
    

How fast is fast enough, and what happens when traffic grows tenfold? This chapter explains where the time goes and how to keep it small.

Where the time goes

Total response time for one call is the sum of several parts: the trip from the client to the gateway, the gateway’s own checks, the trip to the backend, the backend’s work, and the return journey. The gateway adds a small overhead for checks, usually a few milliseconds, which is tiny compared with network distance or a slow database. Most performance problems live in the backend and in geography, not in the gateway itself. Measure before you guess.

Cold starts

Serverless backends may need time to start when they have been idle or when traffic jumps suddenly. The first requests in such moments are slower. You can soften this by keeping a minimum number of instances warm, by making startup work lighter, and by choosing runtimes that start quickly. Warm instances cost a little money even when idle, so balance cost against the smoothness your users need.

Scaling behavior

The gateway itself is a managed service and is designed to handle changes in traffic without you adding servers. Documented limits on request rates and sizes exist, so for very large workloads confirm the current figures and, if needed, ask Google about higher capacity. The backends scale on their own rules, such as the number of simultaneous requests per instance. The weakest link sets the real limit, and it is often the database behind the backend.

Practical speed-ups

flowchart LR
  C["Client"] -->|"network: depends on distance"| G["Gateway checks: small overhead"]
  G -->|"network inside Google: small"| B["Backend startup: cold start if idle"]
  B --> W["Backend work and database: usually the biggest part"]
  W --> R["Response travels back"]
    

Money matters for every design. Prices change, so this chapter explains the shape of the costs rather than quoting numbers.

The pricing idea

API Gateway has generally been priced by the number of calls processed, often with a free allowance each month and a lower price per call at higher volumes, plus charges for data leaving Google Cloud. There is no cost for idle servers because there are no servers for you to run. Always read the current pricing page and use the pricing calculator for estimates, because details and amounts can change.

Costs beyond the gateway

The gateway call is often the smallest part of the bill. The larger costs are usually these.

• Backend compute: functions or containers billed by run time, memory, and number of requests.
• Data and databases: storage, reads and writes, and the instances that serve them.
• Network traffic out: data sent to the internet or to other regions.
• Load balancer and protection: if used for custom domains and web protection.
• Logging and monitoring: large volumes of logs can become surprisingly expensive.
• People time: building, maintaining, and supporting the API.

Controlling cost

Cost comparison thinking

When comparing options, count the whole cost. A gateway that charges per call may look cheap or expensive depending on traffic. At low volume, a managed gateway with per-call pricing is usually the cheapest and simplest choice. At very high volume, fixed-capacity products or self-managed tools might cost less per call, but they bring operating costs and staff time. Compare at your expected volume, not at the extremes.

flowchart TD
  Cost["Monthly API cost"] --> A["Gateway per-call charges"]
  Cost --> B["Backend compute"]
  Cost --> C["Database and storage"]
  Cost --> D["Network egress"]
  Cost --> E["Load balancer and protection"]
  Cost --> F["Logs and monitoring"]
    

Google Cloud offers several ways to put a front door on a service. Picking the right one saves months of rework.

The main options

API Gateway is a light, managed gateway for serverless backends, driven by an OpenAPI document. Apigee is a full API management platform with developer portals, advanced policies, analytics, and monetization for large programmes. Cloud Endpoints is an earlier service that uses the same proxy technology and can be deployed with backends on other Google Cloud platforms, and it requires more setup of the proxy itself. Cloud Load Balancing is not a gateway in the API sense, but it distributes traffic, terminates secure connections, and supports web protection, and it is often combined with a gateway. Calling Cloud Run directly is the simplest option, where the service itself handles authentication and the public address.

Product capabilities and lifecycle status change over time, so confirm the current documentation before deciding. This table is a teaching guide, not a feature guarantee.

A decision flow

flowchart TD
  S["Start: I need to expose an API"] --> Q1{"Only one service and simple needs?"}
  Q1 -->|"Yes"| D1["Call Cloud Run directly with built-in authentication"]
  Q1 -->|"No"| Q2{"Need developer portal, monetization, or advanced policies?"}
  Q2 -->|"Yes"| D2["Consider Apigee"]
  Q2 -->|"No"| Q3{"Serverless backends and OpenAPI contract?"}
  Q3 -->|"Yes"| D3["API Gateway"]
  Q3 -->|"No"| D4["Consider load balancer, Endpoints, or other tools"]
  D3 --> Q4{"Need own domain or web protection?"}
  Q4 -->|"Yes"| D5["Add a load balancer in front"]
  Q4 -->|"No"| D6["Use the default gateway address"]
    

Signs you have outgrown a simple gateway

• External developers ask for sign-up pages, documentation portals, and test consoles.
• You need different plans with different limits, and you want to bill by usage.
• You need to transform messages, call several backends in one request, or apply many custom rules.
• You must manage many APIs across many teams with central governance.

An API has a life: it is planned, built, released, used, changed, and eventually retired. The gateway supports each stage.

Stage by stage

Following the data

Understanding where data travels helps you protect it. A request body from a customer’s phone crosses the internet to the gateway, then moves inside Google’s network to a backend, which may store parts of it in a database or send it to a queue. The reply travels the same path in reverse. At every hop, ask three questions. Is it encrypted? Who can read it? How long does it stay? Logs also hold data, such as paths and sometimes identifiers, so include them in your thinking.

flowchart LR
  P["Customer phone"] -->|"Encrypted over internet"| GW["Gateway: reads headers, checks identity"]
  GW -->|"Encrypted inside Google network"| BE["Backend: processes data"]
  BE --> DB[("Database: stored and encrypted")]
  BE --> Q["Queue: temporary"]
  GW --> LG["Logs: metadata kept for a period"]
  BE --> LG
    

Every tool is a bundle of benefits and costs. Here is an honest balance sheet.

Key trade-offs

Patterns are proven solutions to repeating problems. Anti-patterns are tempting mistakes that cause pain later.

Helpful patterns

Anti-patterns to avoid

A short, practical checklist drawn from everything so far.

Common mistakes and quick fixes

flowchart TD
  E["Error seen by client"] --> A{"Which status class?"}
  A -->|"401 or 403"| B["Check key or token, audience, and invoker permission"]
  A -->|"404"| C["Check path and translation style"]
  A -->|"429"| D["Check quota usage and limits"]
  A -->|"5xx"| F["Check backend health, timeouts, and recent releases"]
  B --> G["Fix and retest on staging"]
  C --> G
  D --> G
  F --> G
    

Manual changes to a live front door are how outages begin. A pipeline turns every release into the same careful routine.

What a good pipeline does

A pipeline is an automated series of steps that runs whenever someone proposes a change. For an API behind a gateway, the pipeline checks the contract, creates a new config, deploys to a staging gateway, runs tests, and only after success promotes the change to production. Because the pipeline always follows the same steps, results are repeatable and each release leaves a record of who changed what and when.

flowchart LR
  PR["Pull request with OpenAPI change"] --> LINT["Check contract style and rules"]
  LINT --> BUILD["Create new API config"]
  BUILD --> STG["Deploy to staging gateway"]
  STG --> TEST["Run functional and security tests"]
  TEST --> APPROVE{"Approved?"}
  APPROVE -->|"Yes"| PROD["Update production gateway"]
  APPROVE -->|"No"| STOP["Stop and report"]
  PROD --> WATCH["Watch errors and latency"]
  WATCH -->|"Problem"| BACK["Roll back to previous config"]
    

Kinds of tests

Environments

Keep separate environments for development, staging, and production, each in its own project where possible. Separate projects keep keys, quotas, and permissions apart, so a test mistake cannot touch real customers. Staging should look as much like production as you can afford: same regions, same authentication, same shape of backends.

Infrastructure described as files

Many teams describe the gateway, the service accounts, and the permissions in configuration files managed by an infrastructure-as-code tool. That way the whole setup can be reviewed, repeated in a new project, and rebuilt quickly after a disaster. Whatever tool you choose, the principle is the same: the repository is the source of truth, and the live system should match it.

Things will go wrong. What matters is how quickly you notice, how little damage spreads, and how calmly you recover.

Scenario catalogue

An incident routine

flowchart TD
  A["Alert: error rate high"] --> B{"Recent release?"}
  B -->|"Yes"| C["Roll back gateway config or backend"]
  B -->|"No"| D{"Backend healthy?"}
  D -->|"No"| E["Fix or scale backend"]
  D -->|"Yes"| F{"Traffic unusual?"}
  F -->|"Yes"| G["Throttle, block, or add edge protection"]
  F -->|"No"| H["Check dependencies and identity provider"]
  C --> I["Confirm recovery in metrics"]
  E --> I
  G --> I
  H --> I
    

Designing for graceful failure

• Timeouts everywhere: never let a call wait forever.
• Retries with care: callers should retry only safe operations, wait a little longer each time, and add random delay so they do not all retry together.
• Clear errors: return useful messages and codes so callers know whether to retry, fix their request, or wait.
• Fallbacks: for non-critical features, show cached or reduced content rather than failing completely.
• Practice: run drills so that the first rollback is not also the first time anyone has tried it.

The gateway idea appears in nearly every industry that exposes services over the internet. These are typical shapes, described loosely.

A common growth story

Many companies follow the same path. They begin with a few functions or services called directly. As partners and mobile apps appear, they add a gateway for consistent authentication and quotas. As the API becomes a product with outside developers, they add a custom domain and web protection. Finally, if they need developer portals and advanced policies, they move to a full management platform. Each step solves a problem the previous step revealed.

flowchart LR
  S1["Stage 1: Direct calls to services"] --> S2["Stage 2: Add a managed gateway"]
  S2 --> S3["Stage 3: Own domain and web protection"]
  S3 --> S4["Stage 4: Full API management platform"]
    

If you are starting from zero, follow this ladder. Each rung takes a few days of reading and practice.

Glossary

This made-up story ties the ideas together. The company and its numbers are fictional.

Imagine a small company called QuickBasket that delivers groceries from local shops. It has a mobile app for customers, a tablet app for shop owners, and a few partner delivery firms. At first, the developers called three Cloud Functions directly from the apps. It worked, until a shop owner’s tablet app was copied by a curious teenager who started calling the order function in a loop. Overnight, the function scaled up and the bill jumped.

The team decided to add a gateway. They wrote an OpenAPI document with four operations: list shops, view the menu, place an order, and check order status. They created one API, one config, and one gateway in a region near their customers. For the customer app, they required sign-in tokens from their identity provider. For the shop tablets, they required a different token audience. For delivery partners, they issued API keys tied to separate projects so each partner had its own quota.

flowchart TD
  CA["Customer app"] -->|"User token"| GW["QuickBasket Gateway"]
  SA["Shop tablet app"] -->|"Shop token"| GW
  PA["Delivery partners"] -->|"API key per partner"| GW
  GW -->|"/shops, /menus"| F1["Function: catalog"]
  GW -->|"/orders"| R1["Cloud Run: orders service"]
  GW -->|"/status"| F2["Function: tracking"]
  R1 --> DB[("Orders database")]
  F2 --> DB
    

What changed

The bumps along the way

The first release failed because the gateway’s service account lacked permission to call the orders service, so every order returned an authorization error. A staging test caught it. A later change used the wrong path style, so the backend received doubled prefixes and returned not found. The team fixed it by switching the translation option and added a test for that path. When a partner’s key leaked into a public forum, the team revoked it, issued a new one, and lowered the quota, all without touching the apps used by customers.

Growth

A year later, QuickBasket opened its API to outside developers. They added a load balancer with their own domain and web protection in front of the gateway, and began evaluating a full API management platform because outside developers wanted a sign-up portal and usage plans. The simple gateway had served them well through the early stages, and the contract-first habit made the move easier because the OpenAPI documents carried over.

Technology alone does not keep an API healthy. Clear ownership and shared habits matter just as much as configuration.

Who owns what

Every API needs a named owner who answers questions, approves changes, and decides when versions retire. Without an owner, small problems linger, documentation rots, and nobody feels responsible when something breaks. Large organizations often split duties between a platform team, which provides the gateway standards, templates, and pipelines, and product teams, which own their specific APIs and backends.

Standards that help

• Naming: consistent path and field names make every API feel familiar.
• Error format: one agreed shape for errors so callers handle them the same way everywhere.
• Review checklist: a short list covering authentication, quotas, logging, and documentation before any release.
• Deprecation policy: a written promise, such as a minimum notice period, so customers can plan.
• Documentation: examples for every operation, kept in step with the contract.

Regular reviews

Schedule a periodic review of each API. Look at who calls it, which operations are unused, which credentials are old, and which permissions are broader than necessary. Remove what nobody needs. Forgotten endpoints and stale keys are the quiet source of many security incidents, and a calendar reminder is a cheap defence.

Culture over tools

The healthiest teams treat the API as a product with customers, even when those customers are colleagues in another department. They publish changelogs, answer questions quickly, collect feedback, and measure satisfaction through usage and support tickets. They celebrate quiet releases and learn from incidents without blaming individuals. Over time, this culture matters more than any single configuration option, because it keeps standards alive after the original authors have moved on to other projects.

flowchart LR
  PT["Platform team: standards and templates"] --> PA["Product team: owns API and backend"]
  PA --> SR["Security review"]
  SR --> PL["Pipeline release"]
  PL --> OC["On-call monitoring"]
  OC --> RV["Periodic review and cleanup"]
  RV --> PA
    

API Gateway gives serverless backends a single, managed front door. You describe your API in an OpenAPI document, turn it into an immutable config, and run it on a regional gateway that checks identity, applies quotas, forwards calls with its own identity, and records everything for monitoring. It is light, simple, and cheap to start with, and it deliberately leaves heavier features to larger platforms. Used with locked-down backends, contract-first design, automated pipelines, and sensible limits, it lets small teams offer reliable, secure APIs without running any gateway servers.