Cloud Endpoints is an API management service that helps you develop, deploy, secure, monitor and control access to your APIs.

The problem it solves

An API, or application programming interface, is a doorway that lets other programs talk to your service. A mobile app asks your API for a customer’s orders. A partner system sends your API a payment request. As soon as an API is opened to the outside world, many questions appear. Who is calling? Are they allowed to? Is one caller sending a million requests and starving everyone else? How many calls did we get yesterday, how fast were they, and how many failed? Which version of the API is each partner using?

If every team answers these questions by writing code inside its own service, the work is repeated again and again, and each service ends up with its own half-finished security and its own slightly different logging. Cloud Endpoints moves these shared concerns out of your business code and into a proxy that sits in front of your service. Your code stays focused on the business problem, while the proxy handles identity checks, usage limits, logging, metrics and tracing in one consistent way.

What it is used for

Teams use Cloud Endpoints to protect public and partner-facing APIs, to require API keys or tokens, to apply per-customer usage limits, to see traffic and error patterns, and to publish a clear description of what an API offers. It works for traditional web APIs that exchange structured text over the web and for high-performance gRPC services.

A small vocabulary makes the rest of the guide easy, so learn these eight terms before moving on.

Google Cloud offers more than one way to manage APIs, and choosing well saves rework.

The neighbors

API Gateway is a fully managed gateway service that is built on the same proxy technology used by Endpoints. You deploy an API configuration and Google runs the gateway for you, so there is no proxy for you to place or operate. Apigee is a full enterprise API management platform with a developer portal, advanced analytics, monetization, mediation and policy tooling, and it suits large programs with many partners. Cloud Endpoints sits between these: you run a proxy yourself, close to your backend, and gain strong control with a lightweight setup.

Endpoints is made of a few clearly separated pieces, each with one job.

The big picture

Two parts live outside your service. The management plane is the Google Cloud side, where your API specification is uploaded, checked and turned into a managed service with a versioned configuration. The data plane is the proxy that you deploy beside your backend, which handles live traffic. When a request arrives, the proxy asks the Google control service whether the call is allowed, using the configuration it downloaded. If the answer is yes, the proxy forwards the request to your backend and returns the response. While doing so, it reports metrics and logs back to Google Cloud for monitoring, logging and tracing.

flowchart LR
  CL["API Clients"] --> PX["Proxy: ESP or ESPv2"]
  PX --> BE["Your Backend Service"]
  PX --> SC["Service Control"]
  SM["Service Management and Configuration"] --> PX
  SC --> MON["Cloud Monitoring"]
  SC --> LOG["Cloud Logging"]
  PX --> TR["Cloud Trace"]
  SPEC["API Specification"] --> SM
        

Each piece in one line

The specification describes the API. Service Management stores it and creates configuration versions. The proxy sits in front of the backend and enforces the rules. Service Control checks keys and quotas and receives usage reports. Monitoring, Logging and Trace turn those reports into dashboards, searchable logs and request timelines.

The proxy is the working heart of Endpoints, and it comes in two generations.

The original proxy

The Extensible Service Proxy, known as ESP, is the original proxy. It is based on a widely used web server and is available as a ready-made container image. It supports web APIs described in a common specification format and also gRPC services.

The newer proxy

ESPv2 is the newer generation, built on Envoy, a modern high-performance proxy widely used in cloud systems. It supports the same kinds of APIs and adds features, better performance and a path that matches how Google’s other gateway products work. For new work, ESPv2 is the usual choice, and it can also be deployed as a standalone service on Cloud Run, which makes a fully serverless setup possible.

What the proxy does for each request

For every call, the proxy checks that the request matches a path and method in the specification. It checks credentials such as API keys or tokens against the rules. It asks the control service about quota. It forwards the request to the backend, observes the response and records the outcome. It can also translate between formats, for example converting an ordinary web request into a gRPC call for the backend.

Everything in Endpoints begins with a written description of the API.

OpenAPI for web APIs

For ordinary web APIs, you write an OpenAPI specification. It lists each path, the methods allowed on it, the inputs it accepts, the outputs it returns and how callers must prove their identity. A single source of truth like this has many benefits. It documents the API for humans, it can be used to generate client libraries and test tools, and Endpoints reads it to build the rules for the proxy.

gRPC for high-performance services

For gRPC services, the description comes from the service definition file together with a compiled descriptor and a small configuration file that sets the service name, authentication rules and quota details. gRPC is popular for efficient communication between services, and Endpoints can protect it in the same way as web APIs.

Google extensions

Endpoints adds its own extra fields to the specification, which let you describe things the standard format does not cover. These extensions set the service name and host, tell the proxy where the real backend lives, define metrics and quotas, and control some behavior such as how long to wait for the backend. They keep all management rules in the same document as the API description.

Deploying an API to Endpoints creates records that are versioned and can be rolled out safely.

The managed service

When you deploy your specification, Endpoints creates a managed service with a unique name, which usually follows a pattern based on the project and a host name. This name is the identity of your API inside Google Cloud, and it is what callers’ projects enable in order to use your API.

Configuration versions

Every deployment of a changed specification produces a new service configuration with its own identifier. Older versions are kept. This means you can always see what rules were active at a given time and can return to an earlier version if a change causes problems.

Rollouts

A rollout decides which configuration the proxies actually use. Proxies can be set to follow the latest version automatically, which is convenient, or to use a pinned version, which is safer for production because nothing changes until you decide. When a proxy starts, it downloads the configuration it was told to use and then enforces it.

Because you run the proxy, you choose where it lives, and each platform has its own pattern.

flowchart LR
  C["Client"] --> LB["Load Balancer or Cloud Run URL"]
  LB --> P1["Proxy Instance"]
  P1 --> B1["Backend on Cloud Run"]
  LB --> P2["Proxy Sidecar in Pod"]
  P2 --> B2["Backend on GKE"]
  P1 -.-> G["Google Control Services"]
  P2 -.-> G
        

Follow a single call from a client to your backend and back to see what the proxy does.

sequenceDiagram
  participant C as Client
  participant P as Proxy
  participant SC as Service Control
  participant B as Backend
  C->>P: Request with credentials
  P->>P: Match path and method
  P->>SC: Check key and quota
  SC-->>P: Allowed
  P->>B: Forward request
  B-->>P: Response
  P-->>C: Response
  P->>SC: Report usage and logs
        

Endpoints supports several ways for callers to prove who they are, and each suits a different situation.

How token checking works

A token is a small signed message that carries claims, such as who the user is, who issued the token and who it is meant for. The proxy checks the signature using the issuer’s public keys, which it fetches and caches. It checks that the issuer is trusted, that the audience matches your API and that the token has not expired. Because the check is done locally with cached keys, it adds very little delay to each call.

The proxy protects the front, but the backend must also trust that traffic really came through it.

Proving the proxy’s identity

A common setup is for the proxy to attach its own identity token when calling the backend. On Cloud Run, for example, the backend can be set to accept only authenticated callers, and the proxy’s service account is the only one granted permission to invoke it. A direct call from anyone else is then refused by the platform before the backend sees it.

Passing the caller’s identity along

After verifying a user’s token, the proxy can pass details of that verified identity to the backend in a standard header. The backend can use this to apply its own rules, for example showing a customer only their own orders. The backend should trust this header only when it knows the request came through the proxy, which is why locking down direct access is so important.

Network protection

Backends can be placed on private networks, with firewall rules that accept traffic only from the proxy. Encryption in transit should be used between client and proxy, and ideally between proxy and backend. Perimeter controls can further limit which networks may reach the services.

Quotas keep one caller from using more than a fair share and protect your backend from overload.

Metrics and limits

Quota in Endpoints works in two steps. First you define a metric, which is a countable thing such as “read requests”. Then you define limits on that metric, such as a number of requests per minute for each consumer project. Methods in your API are tied to metrics, and each call counts a set amount against the metric, which lets you charge more for heavy operations than for light ones.

Who the limit applies to

Limits are applied per consumer, which usually means per project identified by its API key. Limits can be set per minute and per day. If a consumer goes over its limit, further calls are refused with a standard error until the period resets. Different callers can be given different limits through separate quota settings in their own projects, which supports tiered plans such as free and paid.

Callers must be known to Google Cloud before they can use a protected API.

How a consumer gets access

For an API that requires keys, a calling application creates a key in its own Google Cloud project and enables your managed service in that project. The key then identifies the project when calls arrive. The owner of the API can see usage by consumer project, apply different limits to different projects and block a project that misbehaves.

Restricting what a key can do

Keys can be restricted so that they work only for specific APIs and only from certain sources, such as particular websites, mobile applications or network addresses. Restrictions reduce the damage if a key leaks, because a stolen key that is locked to certain places or services is far less useful.

Controlling who may use the API

Identity and Access Management controls who can manage the Endpoints service itself, such as deploying new configurations or viewing usage. Separate permissions exist for people who administer the service, people who may only view reports, and consumers who may enable the API in their projects. Keep administrative rights narrow, since they control what every caller experiences.

Because every call passes through the proxy, Endpoints gives you a rich picture of traffic with almost no extra work.

Metrics and dashboards

Endpoints reports metrics such as request counts, error rates, response times and the sizes of requests and responses, broken down by method, by response code and by consumer. These appear in dashboards and can drive alerts, so you can see which methods are slow, which consumers produce the most traffic and how the error rate changes after a release.

Logs

The proxy writes a record of each request, including the method, path, response code, latency and the consumer identity. These logs go to Cloud Logging, where they can be searched, filtered and exported. Because they include consumer identity, they help to answer questions such as who was calling an endpoint when errors rose.

Tracing

The proxy can add trace information to requests, which lets Cloud Trace show how long each part of a call took, including the time spent in the proxy and in the backend. Passing trace headers on to downstream services gives an end-to-end timeline of one request across several services.

An API is only useful if others can understand and use it easily.

The specification as documentation

Because your API is described in a standard format, many tools can turn it into readable documentation, interactive try-it-out pages and ready-made client libraries in several languages. This means developers can explore your API without reading code, and your documentation stays in step with the real behavior when it is generated from the same specification.

Developer portal options

Endpoints has offered a developer portal feature for publishing API documentation and letting developers try calls and manage keys. Features around portals have changed over time, and organizations that need a rich, branded portal with onboarding, analytics and monetization often choose Apigee instead. Check the current documentation for what Endpoints provides today.

Versioning

APIs change over time, and callers depend on stable behavior. A common approach is to put a version in the path, so a new version can live beside the old one for a transition period. Endpoints can host several versions in the same specification or as separate services. Announce changes early, keep old versions running for a stated time and use usage data to know when it is safe to retire them.

Because the proxy sits on the path of every call, its health and speed matter for your whole API.

The proxy adds a small delay

Every call passes through one more hop, which adds a small delay, usually a few milliseconds. Local token checks and cached configuration keep this low. The control service call for key and quota checks is done efficiently and does not stand in the way of most requests, but it is still worth measuring in your own setup.

Scaling the proxy

The proxy must scale with the backend. On Cloud Run it scales automatically. On Kubernetes, a sidecar scales with each backend copy, or a separate deployment can be scaled with its own settings. On virtual machines, a group of proxy machines behind a load balancer can scale out on demand. In all cases, the proxy should have at least as much capacity as the backend behind it, or it becomes the bottleneck.

What happens when the control service is unreachable

Proxies cache configuration and keys, so they can continue to serve most calls during brief connectivity problems with the control services. Behavior around key checks and quota during longer outages depends on settings and versions, so test failure scenarios and understand them before an incident rather than during one.

Experienced teams reuse a few well-tested layouts.

flowchart TD
  C["Clients"] --> PX["ESPv2 on Cloud Run: public"]
  PX --> A["Orders Service: private"]
  PX --> B["Customers Service: private"]
  PX --> D["Inventory Service: private"]
  PX -.-> M["Metrics, Logs and Traces"]
        

Anti-patterns to avoid

Endpoints cost has two parts, the service itself and the infrastructure you run for the proxy.

What you pay for

At the time of writing, Endpoints charges based on the number of API calls handled, with a free monthly allowance and a lower price per call as volume grows. In addition, you pay for the compute that runs the proxy, such as Cloud Run instances, Kubernetes resources or virtual machines, and for any logging, monitoring and trace data stored. Exact prices and allowances change, so always check the official pricing page before budgeting.

Ways to spend wisely

A short checklist of habits that separate calm API teams from stressed ones.

Best practices

Common mistakes

Stories show how the pieces combine in real organizations.

No service is perfect, and a mature team knows both sides before committing.

Choosing your approach

Quick answers to the questions beginners ask most often.

No. Your API runs on your own backend, such as Cloud Run, Kubernetes or virtual machines. Endpoints provides the proxy and management layer in front of it.

ESP is the original proxy based on a web server. ESPv2 is the newer generation built on Envoy, and it is generally the preferred choice for new deployments, including standalone use on Cloud Run.

Both use similar proxy technology. With Endpoints you deploy and run the proxy yourself. With API Gateway, Google runs the gateway for you, so there is less to operate but also less control.

Web APIs described with OpenAPI and gRPC services described with their service definitions. It can also translate web requests into gRPC calls for the backend.

No. Keys identify a project and support quotas, but they are easy to copy. Combine them with token-based authentication, and keep backends private.

You define metrics and limits in your specification and tie methods to metrics with a cost per call. The proxy reports each call and refuses calls from consumers who have exceeded their limits.

Yes. Endpoints can validate tokens from any provider that follows the common token standard, as long as you configure the issuer, the accepted audience and the location of the verification keys.

Make the backend private. Require authenticated callers or restrict network access so only the proxy’s identity can reach it, and do not trust forwarded identity details on a directly reachable backend.

A new configuration version is created. Proxies adopt it according to their rollout setting, either automatically or only when pinned to the new version, and you can return to an earlier version if needed.

In Cloud Monitoring dashboards for metrics, Cloud Logging for request records and Cloud Trace for timing. All three use data reported by the proxy for every call.

It adds a small delay, since each call passes one more hop. Local token checks and cached configuration keep it low, but you should measure it in your own environment and size the proxy properly.

It depends on your needs. Check the current official guidance, since newer projects are sometimes recommended to use API Gateway or Apigee. Endpoints remains a good fit when you want a lightweight proxy that you control, placed next to your backend.

Cloud Endpoints is the reception desk of your API. You describe the API in a specification, deploy it to create a versioned managed service and run a proxy, ESP or the newer ESPv2, beside your backend on Cloud Run, Kubernetes, virtual machines or other platforms. For every call, the proxy matches the path, checks the caller’s key or token, applies quotas, forwards the request and reports metrics, logs and traces. Together with a private backend and layered authentication, this gives you a secure, observable and fair API without filling your business code with cross-cutting concerns. It is one of several options, alongside the fully managed API Gateway and the full-featured Apigee, so the right choice depends on how much control, convenience and platform capability you need. Teams that treat the specification as a contract, secure the backend properly, set sensible quotas and watch the right signals run APIs that stay trustworthy as they grow.