How Requests are Routed

This page describes how HTTP requests from users reach the appropriate version of a service. Requests can be routed two ways:

  • App Engine's default routing rules apply to requests with a URL that ends at the domain level.
  • Alternatively, you can use a dispatch file that routes specific URL patterns according to your own rules.

If you test your app using the local development server, the available routing and dispatch features are slightly different. To programmatically create URLs that work with both production and development servers, use the ModulesService.getVersionHostname method.

See routing in the development server to learn more.

Requests and domains

App Engine determines that an incoming request is intended for your app by using the domain name of the request. A request whose domain name is is routed to the app whose ID is MY_PROJECT_ID. Every app gets an domain name for free.

The domains also support subdomains of the form, where SUBDOMAIN can be any string allowed in one part of a domain name, excluding the . character. Requests that are sent to any subdomain in this way are routed to your app.

You can set up a custom top-level domain using G Suite and then assign subdomains of your business's domain to various apps, such as Google Mail or Sites. You can also associate an App Engine app with a subdomain. For more information about mapping a custom domain to your app, see Using Custom Domains and SSL.

Requests for these URLs all go to the version of your app that you configured to receive traffic. Each version of your app also has its own URL, so you can deploy and test a new version before configuring that version to receive traffic. The version-specific URL uses the ID of a specific version in addition to the domain name, for example: You can also use subdomains with the version-specific URL: See Routing via URL for more information and examples.

The domain name used for the request is included in the request data that is passed to your app. Therefore, you can use the request data to control how your app responds based on the domain name in the request. For example, if you want to redirect to an official domain, you can code your app to check the Host request header and then respond accordingly based on the domain name.

Routing via URL

You can target an HTTP request with varying degrees of specificity. In the following examples, can be replaced with your app's custom domain if you have one. The URL substrings VERSION_ID, SERVICE_ID, and MY_PROJECT_ID, each represent the resource IDs of your app.

Tip: You can use the following tools to retrieve the IDs of your app's resources:


In the GCP Console, you can view the corresponding Instances, Services, and Versions pages.


Run the gcloud app instances list command to list the resource IDs within a specific GCP project.


To programmatically retrieve resource IDs, see the list methods in the Admin API.

Default routing

The following URL patterns have a default routing behavior. Note that the default routing is overridden if there is a matching pattern that you have defined in your dispatch file:

  • Sends the request to an available instance of the default service:

    Requests are received by any version that is configured for traffic in the default service.

  • Sends a request to an available instance of a specific service:

    Requests are received by any version that is configured for traffic in the targeted service. If the service that you are targeting does not exist, the request gets soft routed.

  • Sends a request to an available instance of a specific version in the default service:

    When a service is not targeted, requests are sent to the default service.

Soft routing

If a request matches the portion of the hostname, but includes a service, version, or instance name that does not exist, then the request is routed to the default service. Soft routing does not apply to custom domains; requests to them will return a HTTP 404 status code if the hostname is invalid.

Targeted routing

The following URL patterns are guaranteed to reach their target, if they exist. These requests are never intercepted and rerouted by the patterns that you have defined in your dispatch file:

  • Sends the request to an available instance of a specific service and version:
  • If you are still using backends or have manually-scaled services, you can target and send a request to a instance by including the instance ID. The instance ID is an integer in the range from 0 up to the total number of instances that are running, and can be specified as follows:

    Sends a request to a specific service and version within a specific instance:

Default service

The default service is created when you deploy the initial version of your app to App Engine. Requests that specify no service or an invalid service are routed, to the default service. Those requests are then handled by the versions that you have configured to receive traffic within the default service. You can see which versions are configured for traffic in the Versions page of the GCP Console.

Restricting access to a service

All services are public by default. If you want to restrict access to a service, add the <role-name>admin</role-name> element to its security constraint


To help demonstrate the URL patterns, assume an example GCP project with ID requestsProject exists and includes an app that is running two services and versions. The example app's default service includes version vFrontend, and the second service service2, includes version vBackend.

To target specific services and versions, you can use the following URL patterns:

  1. To target the version in the default service using HTTPS, you can use:
  2. To target the vBackend version using a custom domain without HTTPS, you can use:

    where is mapped to the domain.

Routing with a dispatch file

For URLs that use the patterns described earlier, you can create a dispatch file to override App Engine's routing rules and define your own custom routing rules. With a dispatch file, you can send incoming requests to a specific service based on the path or hostname in the request URL.

For example, you can create a dispatch file to route mobile requests like to a mobile frontend, route worker requests like to a static backend, and serve all static content from a default service.

For details about creating a dispatch file, see the dispatch.yaml reference.

Uploading the dispatch file

To upload the dispatch file, use the appcfg update_dispatch command, and specify the war directory for the default service. Be sure that all the services mentioned in the file have already been uploaded before using this command. # cd to the war directory containing the default service update_dispatch .

You can also upload the dispatch file at the same time you upload one or more services, by adding the optional auto_update_dispatch flag, which can be used in two forms: --auto_update_dispatch update <app-directory>|<files...> -D update <app-directory>|<files...>

For more information about the deployment commands, see Deploying a Java App.

Routing in the development server

Discovering instance addresses

The local development server creates all instances at startup. Note that at this time basic scaling instances are not supported on the local development server. Every instance that is created is assigned its own port. The port assignments appear in the server's log message stream. Web clients can communicate with a particular instance by targeting its port. Only one instance (and port) is created for automatic scaled services. It looks like this in the server log (note that services were previously called modules):

INFO: Module instance service-auto is running at http://localhost:37251/

A unique port is assigned to each instance of a manual scaled service:

INFO: Module instance service-manual instance 0 is running at http://localhost:43190/
INFO: Module instance service-manual instance 1 is running at http://localhost:52642/

In addition, each manual scaled service is assigned one extra port so clients can access the service without specifying a specific instance. Requests to this port are automatically routed to one of the configured instances:

INFO: Module instance service-manual is running at http://localhost:12361/

The following table shows how these services can be called in the development server and in the App Engine environment:

Service Instance Development server address App Engine address
service-auto (not used) http://localhost:37251/ http://v1.service-auto.[PROJECT_ID]
service-manual 0 http://localhost:43190/ http://0.v1.service-manual.[PROJECT_ID]
service-manual 1 http://localhost:52642/ http://1.v1.service-manual.[PROJECT_ID]
service-manual (not used) http://localhost:12361/ http://v1.service-manual.[PROJECT_ID]

If you are using the Maven or Gradle plugins, you can assign which port number is used by the local development server. For details, see Apache Maven, Apache Maven (Cloud SDK-based), or Gradle.

Dispatch files

All dispatch files are ignored when running the local development server. The only way to target instances is through their ports.

Send feedback about...

App Engine standard environment for Java