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.

These options apply only to deployed apps. When you are testing locally,
the routing behavior depends on the particular runtime and development
environment that you're using.

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
http://[YOUR_PROJECT_ID].appspot.com is routed to the app whose ID is
[YOUR_PROJECT_ID]. Every app gets an
appspot.com domain name for free.

The appspot.com domains also support subdomains of the form
[SUBDOMAIN]-dot-[YOUR_PROJECT_ID].appspot.com, 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 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 Securing Custom Domains with 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 appspot.com domain name, for example:
http://[VERSION_ID]-dot-[YOUR_PROJECT_ID].appspot.com.
You can also use subdomains with the version-specific URL:
http://[SUBDOMAIN]-dot-[VERSION_ID]-dot-[YOUR_PROJECT_ID].appspot.com.
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.

Note: Google recommends
using the HTTPS protocol to send requests to your app. Google does not issue SSL
certificates for double-wildcard domains that are hosted at appspot.com.
Therefore, HTTPS requests must use the string "-dot-" as the URL notation,
instead of "." for separating subdomains. You can use the simple "." URL
notation with your own custom domains and other HTTP addresses. For more
information, see the HTTP and HTTPS examples in the following sections.

Routing via URL

You can target an HTTP request with varying degrees of specificity. In the
following examples, appspot.com 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:

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

Soft routing

If a request matches the [YOUR_PROJECT_ID].appspot.com 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:

Note: In the flexible environment, targeting an instance is not
supported. It is not possible to send requests directly to 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.

Example

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:

To target the version in the default service using HTTPS, you can use:

To target the vBackend version using a custom domain without HTTPS, you can
use:

http://vBackend.service2.example.net
http://vBackend.example.net

where requestsProject.appspot.com is mapped to the example.net 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 host name in the request URL.

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

Notes:

The rules that you define in your dispatch file must use HTTP URL patterns
that include the "." notation for separating subdomains. URLs
defined with the HTTPS "-dot-" notation are not supported.

Dispatch rules also apply to the URLs that you define in your cron file.

Creating a dispatch file

The dispatch file should be placed
either in the root of your project directory, or in the root
directory of your default service.
You can define up to 20 routing rules in the dispatch file and each rule
consists of both the service and url elements.

For example, you can create a dispatch file to route mobile requests like
http://simple-sample.appspot.com/mobile/ to a mobile frontend, and route worker
requests like http://simple-sample.appspot.com/work/ to a static backend: