An API management service from Google Cloud that protects, monitors and controls access to your APIs.

An API is a set of doors that one piece of software uses to talk to another. A mobile app asks a server for a list of orders. A website asks a server to save a new customer. Each of these requests goes through an API. As soon as an API is used by more than a handful of people or programs, you need answers to hard questions. Who is calling? Are they allowed? How often are they calling? Is anything breaking? Which method is the slowest?

Cloud Endpoints is Google Cloud’s service for answering those questions. It is an API management system that helps you develop, deploy, secure and monitor your APIs. You describe your API in a specification file, you place a small proxy in front of your backend, and Google’s management services take care of checking credentials, collecting logs and metrics, and enforcing the rules you chose.

You can describe an API with an OpenAPI specification or with gRPC. Your backend can run on several Google Cloud compute platforms. The backend itself stays yours, written in the language you like, hosted where you like. Cloud Endpoints never replaces your business logic. It wraps it.

What it is not

Cloud Endpoints is not a place to run your code, not a database, and not a full enterprise API marketplace. It does not write your API for you. It manages an API that you have already designed. Keeping that boundary in mind makes it much easier to decide when it is the right tool, a point we return to near the end of this guide.

An unmanaged API works fine on day one and becomes a headache by month six.

Most teams build their first API in a hurry. It returns data, it works, and everyone is happy. Over time, more clients start using it. Partners ask for access. A mobile team ships a bug that sends ten thousand requests a minute. A former employee still holds a working secret. Nobody can say which endpoint is slowest. This is the moment when API management stops being a luxury.

Why not just write this inside every backend?

You could add identity checks, counters and logging into every service you write. Many teams start exactly this way. The trouble is repetition and drift. Ten services mean ten slightly different implementations of the same checks, each with its own bugs. Moving the common work into one shared layer in front of the backends means the checks are written once, tested once and kept consistent. Developers then spend their time on what makes the product special.

Eight terms unlock almost every sentence in the official documentation.

Every platform has its own language. Learn these terms once, and the rest of this guide reads like everyday English.

A few more words appear later. A sidecar is a proxy that runs right next to each backend instance. A remote proxy is a separate proxy service that sits in front of one or more backends. A trace token is a small label added to each request so its timing can be followed.

A proxy that your traffic meets first, and Google services that decide, record and report.

The cleanest way to understand Cloud Endpoints is to split it into two halves. One half sits in your project: the proxy and your backend. The other half is run by Google: the services that store configuration, make decisions and collect data. The proxy is the messenger between the two halves.

flowchart LR
  C["API client"] --> P["Proxy: ESP or ESPv2"]
  P --> B["Your backend"]
  P -->|loads configuration| SM["Service Management"]
  P -->|Check and Report| SC["Service Control"]
  P -->|trace data| CT["Cloud Trace"]
  SC --> CL["Cloud Logging"]
  SC --> CM["Cloud Monitoring"]
  CL --> CO["Google Cloud console"]
  CM --> CO
        

The main building blocks

Two proxy generations, with different engines and different places they can run.

Both ESP and ESPv2 do the same conceptual job. They fetch the service configuration, check each request against it, call Service Control, and pass allowed requests to the backend. They differ in the engine underneath and in the platforms they support.

How to choose

For a brand-new project, ESPv2 is generally the natural starting point, because it supports more platforms, including the serverless ones that many teams use today. ESP remains relevant for older deployments that already run it, and you can keep them running while you plan a gradual move. Always check the current documentation for the exact list of supported platforms before you commit, because platform support changes over time.

Cloud Endpoints Frameworks: a third option

There is also a different flavour called Cloud Endpoints Frameworks, aimed at the App Engine standard environment. With Frameworks, you build the API using annotations and libraries in the code itself instead of writing a specification file by hand, and the framework generates the description for you. Google’s documentation provides a comparison page that explains how Frameworks differ from using ESP. For teams outside App Engine, or teams that prefer a specification-first approach, the proxy approach is the one to learn.

The proxy can live next to each backend or stand alone in front of many.

Where you place the proxy changes your network path, your cost and your operations. Google describes two main modes.

flowchart TD
  subgraph SIDE["Sidecar mode"]
    C1["Client"] --> S1["Proxy container"]
    S1 -->|local call| B1["Backend container"]
  end
  subgraph REMOTE["Remote proxy mode"]
    C2["Client"] --> R1["Standalone proxy service"]
    R1 --> B2["Backend A"]
    R1 --> B3["Backend B"]
  end
        

Sidecar mode

In sidecar mode, the proxy runs in a container alongside each backend instance, for example in the same Kubernetes pod. Because they live together, the hop from proxy to backend is local, so there is no extra network trip. This suits web APIs and microservices where you want each service to carry its own protection. The trade-off is that you deploy and update a proxy with every backend.

Remote proxy mode

In remote proxy mode, ESPv2 runs as its own standalone application, commonly on Cloud Run, and serves as the front for backends elsewhere. This is especially useful for serverless backends that cannot easily host a sidecar. One proxy instance can serve more than one backend, and routing to each backend is configured through a Google-specific extension field in the API description, named x-google-backend. The trade-off is one extra network hop and one more service to run.

The API description is the contract that drives everything else.

In Cloud Endpoints, the description of your API is not documentation that sits on a shelf. It is the working configuration that the proxy actually uses. A change in the description changes how the proxy behaves.

OpenAPI

OpenAPI is a widely used standard for describing web APIs that use ordinary HTTP. A description lists every path, the methods allowed on it, what each one accepts and returns, and which security rules apply. ESPv2 works with OpenAPI version 2.0. Because OpenAPI is a common standard, many tools can read it, which means you can generate client libraries, test tools and documentation from the same file.

gRPC

gRPC is a high-performance way for programs to call each other, often used between internal microservices. Instead of free-form paths and JSON, you define services and messages in a strongly typed format, and both sides generate code from it. Endpoints can place its management layer in front of gRPC services as well, bringing the same authentication, logging and monitoring.

What goes into an Endpoints configuration

Follow a single request from the client to the backend and back, step by step.

Understanding the life of one request clears up most confusion about Cloud Endpoints. Everything else, from authentication to monitoring, is a variation on this journey.

sequenceDiagram
  participant C as Client
  participant P as Proxy
  participant SC as Service Control
  participant B as Backend
  participant L as Logging and Monitoring
  C->>P: Send API request with key or token
  P->>P: Match request to configured method
  P->>P: Validate token signature and audience
  P->>SC: Check - is this call allowed?
  SC-->>P: Allow or deny decision
  alt Allowed
    P->>B: Forward request
    B-->>P: Response
    P-->>C: Return response
  else Denied
    P-->>C: Return error to client
  end
  P->>SC: Report - what happened
  SC->>L: Write logs and metrics
        

The journey in plain steps

Why this design is clever

Because the proxy has already loaded the rules, most of the routine work is done close to your backend, so requests stay fast. Only the parts that genuinely need Google’s central knowledge cross over to Service Control. Meanwhile, your backend can assume that anything which reaches it has already been checked, which keeps backend code simple.

Write the contract, publish it, deploy the proxy, and roll out changes with care.

Putting an API under Endpoints management follows a repeatable path. Knowing the stages helps you plan who does what and where mistakes are most likely to appear.

flowchart TD
  A["Design the API contract"] --> B["Write the Endpoints configuration"]
  B --> C["Publish it to Service Management"]
  C --> D["Deploy backend with proxy"]
  D --> E["Proxy loads service configuration"]
  E --> F["Clients call the API"]
  F --> G["Observe logs, metrics, traces"]
  G --> H{"Change needed?"}
  H -->|Yes| B
  H -->|No| F
        

Stage by stage

An important detail about updates

The proxy loads its configuration when it starts, as the documentation describes it. That means publishing a new configuration in Service Management is not the same as having the running proxies use it. The proxies must be told to pick up the new version, usually by redeploying or restarting them against the new configuration. Many teams are surprised when a published change seems to have no effect, and this is almost always the reason.

Roles in the lifecycle

Different people touch different stages. API designers own the contract. Backend developers own the implementation. Platform or operations engineers own the proxy deployment. Security reviewers check the authentication rules. Support teams read the dashboards. Writing this division down early avoids the situation where everyone assumes someone else is watching the controls.

API keys, signed tokens and service accounts each answer the identity question in a different way.

Authentication means proving identity. Cloud Endpoints supports several approaches, and you can use different ones for different methods in the same API. Choosing well is one of the most important decisions in your design.

API keys: simple and limited

An API key is a long string that a client includes with each request. Service Control checks that the key is valid and that the project it belongs to has enabled your API. This gives you a clear picture of which application is calling, which is useful for counting and for quotas. But a key only identifies the project, not a particular person, and anyone who obtains the key can use it. Treat keys as identifiers, not as strong secrets.

JWT validation: stronger identity

A JSON Web Token is a signed pass issued by an identity provider after the user signs in. The proxy checks two things: that the signature is genuine, and that the token was intended for your API, which is called the audience. Tokens can also carry facts about the user, called claims, and expire after a short time, which limits the damage if one leaks.

Service accounts and Google ID tokens

When one Google Cloud service calls another, a person is not involved. Instead, the calling service runs as a service account and presents an ID token that proves it. The proxy validates this token like any other. This keeps microservice traffic authenticated without sharing long-lived secrets between teams.

Mixing methods

A single API often needs several. For example, public read-only methods might need only an API key so you can count usage, while methods that change data require a signed user token, and internal admin methods require a service account. Because the rules are written per method in the description, you can fine-tune each door.

Knowing who your consumers are is the base for quotas, billing insight and support.

In Endpoints, a consumer is the project that calls your API. Each consumer has to enable your API in their own project before an API key from that project will be accepted. This simple rule is powerful, because it ties every call to a known project that you can measure, limit and, if necessary, switch off.

How a consumer gets access

Practical uses of consumer identity

• Support. When a partner reports errors, you can filter logs and graphs to that one consumer.
• Fair use. Limits can be applied per consumer, so a heavy user does not harm others.
• Planning. You can see which consumers are growing and plan capacity for them.
• Offboarding. If a partner relationship ends, disabling the API in their project or deleting their key closes the door cleanly.

Restricting keys

Consumers should restrict their keys to the minimum: only your API, and where possible only certain applications or network addresses. A restricted key that leaks is far less dangerous than an unrestricted one. As an API owner, publish this advice in your onboarding material, because you cannot control how consumers store their keys.

Limits protect your backend, your budget and your other customers.

Even honest clients can cause trouble. A bug in a loop, a sudden marketing success or an overeager integration can multiply traffic overnight. Quotas place a ceiling on how much each consumer may use, so one party cannot exhaust capacity that everyone shares.

What a quota is

A quota is a numeric limit on usage over a period, for example a maximum number of calls per minute for each consumer project. You define the limits in your API configuration, assign a cost to each method if some are heavier than others, and the management layer enforces them using the consumer identity from the API key. Details of the exact configuration fields live in Google’s quota documentation, and you should read the current version before designing limits because capabilities are refined over time.

Designing sensible limits

The proxy is a strong front door, but it works best inside a well-secured building.

Security is more than turning on authentication. It covers how traffic is encrypted, who may change the configuration, how secrets are handled and whether attackers can skip the proxy altogether.

Encrypt traffic

Serve your API over HTTPS so that credentials and data cannot be read in transit. Cloud platforms such as Cloud Run provide HTTPS by default, while on virtual machines or Kubernetes you must arrange certificates and a secure entry point yourself. Also consider the hop between the proxy and the backend, especially in remote proxy mode.

Protect the backend from direct access

The proxy only protects traffic that goes through it. If your backend has a public address and accepts any caller, attackers will simply go around the proxy. Restrict the backend so that it accepts traffic only from the proxy, using network rules, private connectivity or identity checks between the two.

Control who can change the API

• Give only a small group the right to publish new service configurations.
• Require review of description changes, since they change security behaviour.
• Keep a history so you can see who changed what and when.
• Use separate projects for development, testing and production so experiments cannot touch live APIs.

Handle secrets with care

Never store credentials in source code or in the API description. Use Google Cloud’s secret handling features for anything sensitive, and rotate keys on a schedule. When someone leaves the team, review what they could access.

Validate on the backend too

The proxy checks identity and access, but it does not understand your business rules. Your backend should still validate inputs, enforce ownership rules such as a customer seeing only their own orders, and treat every request as potentially hostile.

The same front door that protects your API also records everything that passes through it.

Because every request travels through the proxy and Service Control, Cloud Endpoints gets a consistent record of API activity without you writing counting code in every service. Logs and metrics are delivered to Cloud Logging and Cloud Monitoring, and the Google Cloud console shows graphs and searchable records. Cloud Trace shows how long each request spent in each stage.

The numbers worth watching

Traces: where did the time go?

A trace breaks a slow request into pieces: time in the proxy, time waiting for Service Control and time inside your backend. If the proxy’s share is small and the backend’s share is large, you know where to look. Without traces, teams often blame the wrong layer.

Typical troubleshooting scenarios

Endpoints is billed by API calls, and the proxy and backend have their own compute bills.

Cloud Endpoints pricing is based on the number of API calls handled, reported through Service Control, which shows up as its own line on your bill. According to Google’s pricing page, the first couple of million calls each month are free, calls beyond that are charged at a rate of a few dollars per million, and very high volumes above one billion calls per month fall to a lower per-million rate. Exact numbers and currencies can change, so always check the current pricing page and the Google Cloud pricing calculator.

Keeping the bill sensible

• Estimate monthly call volume early, from real client behaviour rather than guesses.
• Use caching on the client side and sensible polling intervals so clients do not make needless calls.
• Apply quotas so a runaway client cannot generate a surprise bill.
• Review log retention and filtering for very chatty APIs.
• Right-size the proxy instances, since an oversized proxy is wasted money.

Patterns are habits that repeatedly work; anti-patterns are habits that repeatedly hurt.

Teams that run Endpoints for a while tend to converge on the same handful of habits. Here are the useful ones, followed by the traps that catch newcomers.

Patterns that work

flowchart LR
  D["Design contract"] --> R["Review in version control"]
  R --> P["Publish configuration"]
  P --> V["Verify proxies use it"]
  V --> O["Observe dashboards and alerts"]
  O --> I["Improve and iterate"]
  I --> D
        

Anti-patterns to avoid

Endpoints is a lightweight, Google-native option; other tools suit other needs.

Google Cloud offers more than one way to manage APIs, and the right choice depends on your backends, your consumers and how much management you need. The comparison below is deliberately high level, and you should confirm the current capabilities in each product’s documentation.

Situations where Endpoints shines

• Small to medium API programs on Google Cloud. You need identity checks, usage numbers and logs without a heavy platform.
• Microservices with gRPC. You want consistent authentication and metrics for internal APIs.
• Teams who like specification-first work. Your OpenAPI description is already the centre of your process.

Situations where caution is wise

• Very advanced rate limiting and monetisation. If you need detailed pricing plans, developer onboarding portals with approval flows or analytics products, a dedicated enterprise platform is likely a better fit.
• Backends outside Google Cloud. The proxy and management services are designed around Google Cloud platforms, so check carefully before using them elsewhere.
• Teams that cannot run a proxy. If you do not want to operate any proxy at all, consider a fully hosted gateway instead.

An API is a product; the people who call it are your customers.

Protection and monitoring keep an API safe, but they do not make it pleasant. Consumers judge your API by how easy it is to learn, how stable it is and how clearly it explains its mistakes. Because Endpoints is built around a written description, you already hold the raw material for good documentation.

Versioning without drama

APIs change. The challenge is changing them without breaking people who depend on today’s behaviour. Two common approaches are putting a version in the path of every method, and publishing a new configuration for a new version while keeping the old one running for a stated period. Whichever you pick, adopt a clear policy: how long old versions live, how you announce retirement, and what counts as a breaking change.

Documentation from the description

Because OpenAPI is a common standard, many tools can turn the same description into reference pages, example requests and client libraries. Cloud Endpoints also offers developer-portal style documentation features that help consumers explore an API, and third-party reference tools can read the same file. Whatever you choose, keep the description accurate, since stale documentation is worse than none.

Helpful error behaviour

• Return clear messages that say what went wrong and how to fix it.
• Use consistent error shapes across all methods.
• Tell clients when they hit a limit, and when they may try again.
• Never leak internal details such as stack traces or internal addresses.

Four illustrative situations showing where Endpoints fits.

The scenarios below are illustrative composites, not case studies of specific named companies.

A short checklist to keep nearby while you run your API.

Best practices

• Treat the description as code. Version it, review it and test it before it goes live.
• Choose the right proxy for the platform. Check the current supported-platform list before you design your deployment.
• Authenticate by risk. Match the strength of the check to the sensitivity of each method.
• Close the back door. Make the proxy the only way to reach the backend.
• Verify rollouts. After publishing, confirm that each proxy runs the intended configuration version.
• Set quotas early. Protect capacity and budget before traffic grows.
• Monitor and alert. Build dashboards for volume, errors, latency and rejected calls, and test your alerts.
• Document for humans. Provide clear references, examples, limits and a deprecation policy.

Common mistakes

Quick answers to the questions beginners ask most.

It is Google Cloud’s API management service that places a proxy in front of your backend to check callers, enforce rules and record logs, metrics and traces.

ESP is the original NGINX-based proxy. ESPv2 is the newer Envoy-based one, built for high performance and supporting more platforms, including serverless ones such as Cloud Run.

No. The backend stays as it is. You add an API description and place the proxy in front of it.

OpenAPI, using version 2.0 with ESPv2, and gRPC. There is also Cloud Endpoints Frameworks for App Engine.

ESP supports App Engine flexible, Compute Engine, Google Kubernetes Engine and Kubernetes. ESPv2 adds App Engine standard, Cloud Run functions, Cloud Run and Knative serving.

Check happens before the backend is called and decides whether the request is allowed. Report happens afterwards and sends the logging and monitoring data.

For sensitive data, no. A key identifies a calling project, not a person. Combine keys with signed user tokens and enforce ownership rules in the backend.

No. If the proxy or Service Control refuses the call, the backend never sees it, which is why the proxy logs are the first place to look.

Billing is per API call. The first couple of million calls each month are free, with a modest per-million price beyond that and a lower price at very high volumes. You also pay for the compute that runs your backend and proxy. Check the current pricing page for exact figures.

Proxies load their configuration at startup, so running ones keep using the old version until they are redeployed or restarted against the new one.

If you need advanced enterprise API programmes with detailed plans and portals, consider Apigee. If you want a fully hosted gateway for serverless backends, consider API Gateway.

Yes. Service accounts and Google ID tokens let services authenticate to each other, and the proxy can run as a sidecar next to each service.

Cloud Endpoints gives your APIs a dependable front door. You describe the API in an OpenAPI or gRPC configuration, publish it to Service Management, and run a proxy, either ESP or ESPv2, in front of your backend. For each request the proxy applies your rules, Service Control decides whether the call is allowed, and logs, metrics and traces flow into Google Cloud’s observability tools. It is simple, economical and well integrated with Google Cloud, with modest rate-limiting compared with large enterprise platforms.

Remember the receptionist in the office building. The desk checks who you are, notes your arrival and sends you to the right floor, but it does not do the work upstairs. Keep the back doors locked, write a clear contract, and watch the visitor log.