Start with the big picture before we meet the details.

The simple definition

Cloud Endpoints is an API management system. It helps you develop, deploy, protect, and monitor APIs that run on Google Cloud. You describe your API in a standard file. Cloud Endpoints then runs a small proxy in front of your service, which checks each request against the rules you set, forwards good requests to your backend, and reports what happened for monitoring and billing.

Why it exists

Every API needs the same extra features: checking who is calling, limiting how much each caller may use, keeping logs, producing charts, and handling versions. If every team builds these in every service, the work is repeated, and mistakes creep in. Cloud Endpoints moves these shared jobs into one place, in front of the service, so developers write business logic and nothing else.

Where it is used

Teams use it to publish REST APIs and gRPC services to mobile apps, websites, partners, and other internal systems, running on Cloud Run, Kubernetes Engine, Compute Engine, and App Engine.

A few simple ideas make everything else easy.

Keys, tokens, and who is calling

Three words are often mixed up. An API key is a simple code that identifies the project or app making a call. It is useful for counting usage and applying quotas, but it is not strong proof of a person’s identity. A token, such as a JSON Web Token or JWT, is a signed note that proves who the caller is and what they may do, and it is issued by a trusted identity provider. A service account is an identity for programs, used when one service calls another.

Quotas and rate limits

A quota limits how much a caller can use in a period, such as ten thousand requests per day. A rate limit limits how fast, such as ten requests per second. They protect your backend from overload, make costs predictable, and let you offer different service levels to different users.

Here is how a request reaches your service through Cloud Endpoints.

flowchart LR
  A["Client such as mobile app, website, or partner"] --> B["Extensible Service Proxy"]
  B --> C["Your backend service"]
  B  D["Service Control for check and report"]
  E["API specification file"] --> F["Service Management"]
  F --> G["Service configuration"]
  G --> B
  D --> H["Cloud Monitoring"]
  D --> I["Cloud Logging"]
  B --> J["Cloud Trace"]
  K["Identity provider for tokens"] -.-> B
    

The main parts

Where the proxy runs

You can run the proxy in several ways: as a sidecar container next to each service instance, as a separate gateway service that forwards to many backends, or built into your platform choice, for example a container in front of a Cloud Run service. A sidecar is the closest to the service and adds almost no network hop. A central gateway is easier to manage as one unit. Choose by how your teams and traffic are organised.

Everything in Cloud Endpoints starts from a written description of your API.

OpenAPI for REST

OpenAPI is an open standard for describing REST APIs in a structured text file. It lists each path, the methods allowed on it, the inputs, the outputs, and the security rules. Cloud Endpoints has historically worked with the older version of this standard, known as OpenAPI 2.0 or Swagger. Support for newer versions may differ, so check the current documentation before choosing a format.

What the file contains

Special Google extensions

Google adds extra fields, which begin with “x-google”, to carry features that the standard does not cover. These include the backend address and path handling, the trusted token issuers and the keys used to verify them, the allowed audiences, and the quota metrics and limits. Because these are part of the specification, your API’s security and limits live next to its description, are reviewed with it, and are saved in version control with it.

gRPC services

For gRPC, you provide a compiled description of your service, plus a short configuration file in YAML that sets the name, the authentication rules, and optionally the mapping of gRPC calls to ordinary web-style calls. This gives you a strongly typed contract and fast communication between services, while still allowing browser and mobile clients to use a friendly web style when you enable the mapping.

Follow one call from the client to your backend and back.

sequenceDiagram
  participant C as Client
  participant P as Extensible Service Proxy
  participant SC as Service Control
  participant B as Backend Service
  C->>P: Request with API key or token
  P->>P: Match path and method to the specification
  P->>P: Validate the token signature and claims
  P->>SC: Check key, quota, and service status
  SC-->>P: Allowed or denied
  alt Allowed
    P->>B: Forward the request
    B-->>P: Response
    P-->>C: Response returned to the client
  else Denied
    P-->>C: Error such as unauthorised or too many requests
  end
  P->>SC: Report the call with size, time, and status
    

The steps in words

Match. The proxy compares the call with the paths and methods in your specification. An unknown path is refused straight away, which keeps accidental or probing calls away from your backend.

Authenticate. If a token is required, the proxy checks its signature using the issuer’s public keys, checks that it has not expired, and confirms that the issuer and the intended audience are the ones you listed. If an API key is required, it checks that the key exists and is allowed.

Check. The proxy asks Service Control whether this caller may proceed, including whether the service is enabled for the calling project and whether a quota would be exceeded. To save time, results are cached for a short while, and the proxy reports in batches.

Forward. If everything is fine, the proxy forwards the request to your backend, and may add a header that carries details about the verified caller, so your code does not repeat the work.

Report. After the response, the proxy reports the call to Service Control, which feeds your charts and logs.

Failure behaviour

Think about what should happen if the control service is slow or unreachable. The proxy has settings and caching that help it keep serving known callers for a short time. Know how your chosen version behaves, test failure cases, and set timeouts on both the proxy and the backend, so a stuck call does not hold up resources.

The most important job of an API front door is deciding who may come in.

flowchart TD
  A["Who is calling your API"] --> B{"A person using an app"}
  B -->|"Yes"| C["User tokens from Firebase, Auth0, Google, or another trusted provider"]
  B -->|"No"| D{"Another Google Cloud service"}
  D -->|"Yes"| E["Service account with a signed ID token"]
  D -->|"No"| F{"A partner or public developer"}
  F -->|"Yes"| G["API key for usage tracking plus a token for identity"]
  F -->|"No"| H["Private access only, with network controls"]
  C --> I["Proxy verifies signature, issuer, audience, expiry"]
  E --> I
  G --> I
    

Methods supported

How token checking is configured

In the specification you list each trusted issuer, the address of its public keys, and the audiences that your API accepts. A token is accepted only if it is signed by one of the listed issuers, intended for your API, and not expired. Different paths may require different methods, or none at all, such as a public health check.

Authorisation: what are they allowed to do?

Authentication says who someone is. Authorisation says what they may do. The proxy can pass the verified identity and claims to your backend, which then makes business decisions, such as “this user may only see their own orders”. Never assume that a proven identity means unlimited access.

Limits keep your service healthy and your bills predictable.

How quotas are described

In the specification you define named metrics, such as “read requests”, and limits attached to them, such as “one hundred per minute for each consumer project”. Then you mark which paths use which metric, and how much each call costs. For example, a simple lookup may cost one unit and a heavy report may cost ten. Limits can apply per project, so each customer has their own allowance, which is why API keys matter for quotas.

What callers see

When a limit is exceeded, the proxy answers with a clear error, usually the “too many requests” status. Good clients react by waiting and trying again with growing delays. Publish your limits in your documentation, so developers can design for them.

Quotas are not security

Quotas reduce abuse, but a determined attacker may use many keys or many projects. For broad protection against attacks, combine quotas with a web application firewall, bot protection, network limits, and monitoring.

An API has a life from first design to retirement. Cloud Endpoints supports each stage.

flowchart LR
  A["Design the API contract"] --> B["Write the specification"]
  B --> C["Deploy the configuration to Service Management"]
  C --> D["Configuration receives an identifier"]
  D --> E["Build or select the proxy container with that configuration"]
  E --> F["Deploy the backend and proxy to Cloud Run, GKE, or VMs"]
  F --> G["Test, monitor, and gather feedback"]
  G --> H{"Change needed"}
  H -->|"Yes"| B
  H -->|"Retire"| I["Deprecate, notify users, and shut down"]
    

Versioning

Once clients depend on your API, you cannot change it freely. Adding a new optional field is usually safe. Removing a field, changing its meaning, or renaming a path is a breaking change that can crash existing apps. The usual cure is to put a version in the path, such as “v1” and “v2”, run both together for a while, and give users plenty of notice before retiring the old one.

Automation

Treat the specification and deployment steps as code. Keep them in version control, review changes, test against a staging environment, and use a pipeline so that every release follows the same safe steps and can be rolled back to the previous configuration identifier.

An honest view of what you gain and what you give up.

The big trade-offs

Central control versus extra moving parts. A front door gives consistent rules, but is one more thing that must be available, secured, and updated.

Self-run proxy versus fully managed gateway. Running the proxy yourself gives flexibility about where it runs, such as beside services on Kubernetes. A managed gateway removes the work of running it, but gives less placement choice.

Light management versus full platform. Cloud Endpoints covers the essentials. A full platform such as Apigee adds portals, analytics products, monetisation, and a large policy library, with more cost and complexity.

Gateway rules versus backend rules. Put generic checks at the front, such as identity, quotas, and basic validation. Keep business rules inside the backend, where the data is.

An API is a public-facing entrance to your systems. Guard it in layers.

Layers of protection

Key practices

• Do not expose the backend directly. The backend should accept calls only from the proxy or gateway, through network rules and identity checks, or attackers will simply go around the front door.
• Restrict API keys. Limit each key to the API it needs and, where possible, to specific apps or addresses, and rotate keys when staff or partners change.
• Use short-lived tokens. Short lifetimes limit the damage of theft.
• Keep secrets out of the specification. The file is reviewed and shared. Store secrets in a secret manager.
• Use least privilege for service accounts. The proxy and the backend each need only the roles for their own work.
• Control who can change the configuration. A changed configuration can open or close your whole API. Restrict and review those permissions.
• Handle cross-origin requests deliberately. If browsers call your API from other sites, allow only the sites you trust.
• Follow common API security guidance. Protect against object-level access mistakes, excessive data exposure, and broken authentication, which are the most frequent API problems.
• Test. Run security tests and reviews before launch and after big changes.

Cloud Endpoints gives you a clear picture of how your API is used and how it behaves.

What to watch

• Request rate. Sudden jumps or drops can signal attacks, outages, or broken clients.
• Error rates by status. Many “unauthorised” errors may mean expired tokens or a configuration problem. Many server errors point to the backend.
• Latency. Watch the slowest few percent, and compare proxy time with backend time.
• Quota use by consumer. See who is near their limit, and who is abusing.
• Method popularity. Learn which endpoints are used, and which can be retired.
• Proxy health. Memory, CPU, restarts, and instance counts.
• Configuration changes. Alert when a new configuration is deployed, and who did it.

Troubleshooting flow

When a call fails, ask in order: Did the request reach the proxy, or did the load balancer or network stop it? Did the proxy match the path and method? Did authentication pass? Was the quota exceeded or the service not enabled for that project? Did the backend answer, and how quickly? The logs for the request usually name the step where it stopped.

Keep the front door quick and the bill reasonable.

Performance points

• Added delay is small. Caching of checks and batched reporting keep the extra time per call low.
• Size the proxy. It needs enough CPU and memory for your traffic. Use autoscaling where available and set sensible minimum instances.
• Keep the proxy near the backend. Same region, and ideally the same network, to avoid extra delay.
• Set timeouts. Make sure the proxy waits long enough for slow backends and no longer, so resources are freed.
• Use connection reuse. Persistent connections reduce set-up overhead.
• Cache responses where safe. Public, rarely changing data can be cached at the edge with a content delivery network.
• Compress and paginate. Return smaller answers, and break long lists into pages.

What you pay for

Pricing has historically been based on the number of requests, with a free monthly allowance and a price per million requests beyond it. Because pricing and free allowances change, check the current pricing page. You also pay for the compute that runs the proxy and your backend, network traffic, logging, and any load balancers or firewalls.

Helpful habits and harmful habits seen again and again in real projects.

Helpful patterns

Anti-patterns to avoid

More things to steer clear of

• Putting business logic in the gateway. It becomes hard to test and change.
• No quotas at all. One bad client can bring down the service.
• No timeouts. Stuck calls pile up and use all resources.
• Overly chatty APIs. Many tiny calls waste time and money. Offer batch or combined calls.
• Returning too much data. Leaking internal fields creates security and privacy risks.
• Ignoring the proxy’s own health. It is part of your critical path.

A checklist of habits that experienced teams rely on.

Habits that work

• Write the specification first and keep it in version control.
• Require identity with tokens for anything sensitive.
• Restrict API keys and use them for counting usage.
• Set quotas and rate limits and publish them.
• Close the back door. Only the proxy may reach the backend.
• Set timeouts and size limits on every layer.
• Use staging to test each new configuration.
• Roll out gradually and keep the previous configuration ready for rollback.
• Monitor errors, latency, and quotas with alerts.
• Version your API and announce deprecations early.
• Keep secrets in a secret manager, not in specification files.
• Document with examples so developers succeed quickly.

Mistakes beginners often make

Common ways teams use Cloud Endpoints. These are typical scenarios, not claims about any particular company.

Google Cloud has several ways to put a front door on an API. Here is how to choose.

flowchart TD
  A["You need to manage and protect an API"] --> B{"Need portals, monetisation, analytics products, and rich policies"}
  B -->|"Yes"| C["Apigee"]
  B -->|"No"| D{"Backend is serverless such as Cloud Run, Functions, or App Engine"}
  D -->|"Yes, want a fully managed gateway"| E["API Gateway"]
  D -->|"No, runs on GKE or VMs, or you want to run the proxy yourself"| F["Cloud Endpoints with the Extensible Service Proxy"]
  A --> G{"Only need load balancing and edge security"}
  G -->|"Yes"| H["Cloud Load Balancing with Cloud Armor"]
  A --> I{"Need service to service traffic control inside a mesh"}
  I -->|"Yes"| J["Service mesh tools"]
    

A simple rule of thumb: use a managed gateway when you want the least work and your backends are serverless. Use Cloud Endpoints when you want to run the proxy yourself next to services on Kubernetes or virtual machines. Use a full platform when you run an API business with partners and developer communities. Because Google’s guidance changes, check the current recommendation, especially for new projects.

Here is a calm, step-by-step plan for your first protected API.