Architectural overview of Cloud Endpoints

Endpoints is a distributed API management system comprising services, runtimes, and tools. Endpoints provides management, monitoring, and authentication.

The components that make up Endpoints are:

  • Extensible Service Proxy (ESP) - for injecting Endpoints functionality.

  • Service Control - for applying API management rules.

  • Service Management - for configuring API management rules.

  • Cloud SDK - for deploying and management.

  • Google Cloud Platform Console - for logging, monitoring and sharing.

Endpoints architecture

Endpoints architecture

Endpoints components

ESP

ESP is a NGINX-based proxy that runs in front of the backend and injects Endpoints functionality such as authentication, monitoring, and logging. TESP retrieves a service configuration from Service Management and uses it to validate incoming requests.

ESP is designed for you to deploy it in a containerized environment and validate JWTs and Google ID tokens. It employs a variety of techniques, such as heavy caching and asynchronous calls to remain lightweight and highly performant.

Service Control

Service Control applies API management rules at runtime, such as key authentication, monitoring, and logging. Service Control provides the following methods:

  • Check - verifies authentication and API keys, and indicates whether a call should be permitted

  • Report - notifies the systems of record for logging and monitoring

Service Management

You use the OpenAPI specification to describe the surface and the behavior of your API in a text file referred to as the Endpoints configuration. You deploy the Endpoints configuration to Service Management by using the Cloud SDK, which configures the API management rules. Other configuration related tasks also happen here, such as sharing your API with other developers, enabling or disabling the API in different projects, and generating API keys.

The Cloud SDK

The Cloud SDK provides the gcloud command-line tool that you can use to make calls to various GCP services. You use the gcloud command-line tool to deploy your Endpoints configuration to Service Management.

Google Cloud Platform Console

GCP Console is the graphical user interface for Google Cloud Platform (GCP). Endpoints uses the GCP Console to expose monitoring and logging data that are sent from ESP and recorded by Service Control and share APIs with other developers, and for them to generate API keys to call the API.

Deployment scenarios

ESP is designed for you to deploy it in a container alongside each instance of your backend. This server-local topology is ideal for both web-facing APIs as well as microservices. It avoids the network hop typically associated with centralized proxies and allows API management that is highly performant as well as scalable.

Typically, load balancing is applied before traffic hits ESP. On App Engine, load balancing happens automatically. On Compute Engine, it is accomplished via Cloud Load Balancing. For Kubernetes deployments, you can use an ingress proxy for load balancing. In Google Kubernetes Engine, you can use either Cloud Load Balancing or an ingress proxy for load balancing.

Upon startup, ESP obtains its service configuration from Service Management. The service configuration is generated from the OpenAPI specification or from gRPC, the service configuration YAML file. It tells ESP both the surface of the API to be managed along with the policies, such as which methods require authentication, and which require API keys.

Request routing

When a request is received, ESP creates a trace token for Stackdriver Trace.

Next, ESP matches the path of the incoming requests with the surface of the API. After finding a matching route, ESP performs any authentication steps for the specified method.

If JWT validation is necessary, ESP validates the authentication using the appropriate public key for the signer, and validates the audience field in the JWT. If an API key is required, ESP calls the Service Control API to validate the key.

Service Control looks up the key to validate it, and ensures that the project associated with the key has enabled the API. If the key isn't valid or the project hasn't enabled the API, the call is rejected and it is logged via the Service Control API.

If Service Control successfully validates the key, the request along with all original headers, plus a JWT validation header, if appropriate, is forwarded to the backend.

When a response is received from the backend, ESP returns the response to the caller and sends the final timing information to Trace. The callpoints are logged via the Service Control API, which writes metrics and logs to their appropriate destinations.

ESP on Kubernetes

The following diagram shows the overall architecture where ESP runs as a side-car container in front of the API service application container, with my-api API hosted at my-api.com and backed by a Kubernetes service.

Endpoints on Kubernetes overview

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints with OpenAPI
Need help? Visit our support page.