Routing Requests to Modules

HTTP requests from users can reach the appropriate module/version/instance in two ways: A request with a URL that ends at the domain level can be routed according to App Engine's default address routing rules. Alternatively, you can include a dispatch file that routes specific URL patterns according to your own rules.

Addressing instances

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 "instance", "version", "module", and "app-id" represent application and module attributes that you have defined yourself.

Note: Google recommends using the https protocol. As explained below,
https urls must use the separator "-dot-" between subdomains of appspot. You may use a simple
"." with your own custom domain or with http addresses.

These two address forms are guaranteed to reach their target (if it exists). They will never be intercepted and rerouted by a pattern in the dispatch file:

https://instance-dot-version-dot-module-dot-app-id.appspot.com

Sends a request to the named module, version, and instance. This address form can only be used by application administrators.

https://version-dot-module-dot-app-id.appspot.com

Send the request to an available instance of the named module and version (round robin scheduling is used).

These address forms have a default routing behavior. Note that the default routing is overridden if there is a matching pattern in the dispatch file:

https://module-dot-app-id.appspot.com

Send the request to an available instance of the default version of the named module (round robin scheduling is used).

https://version-dot-app-id.appspot.com

Send the request to an available instance of the given version of the default module.

https://app-id.appspot.com

Send the request to an available instance of the default version of the default module.

Please note that in April of 2013, Google stopped issuing SSL certificates for double-wildcard domains hosted at appspot.com (i.e. *.*.appspot.com). If you rely on such URLs for HTTPS access to your application, please change any application logic to use "-dot-" instead of ".". For example, to access version "1" of application "myapp" use "https://1-dot-myapp.appspot.com" instead of "https://1.myapp.appspot.com." If you continue to use "https://1.myapp.appspot.com" the certificate will not match, which will result in an error for any User-Agent that expects the URL and certificate to match exactly.

Default module

The default module is defined by explicitly giving a module the name "default,"
or by not including the name parameter in the module's config file. Requests
that specify no module or an invalid module are routed to the default module.
You can use the Admin Console to designate a default version for a module, when
appropriate.

Soft routing

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

Restricting access to a module

All modules are public by default. If you want to restrict access to a module, add the “login: admin” parameter to its handlers.

Please note that in April of 2013, Google stopped issuing SSL certificates for double-wildcard domains hosted at appspot.com (i.e. *.*.appspot.com). If you rely on such URLs for HTTPS access to your application, please change any application logic to use "-dot-" instead of ".". For example, to access version "1" of application "myapp" use "https://1-dot-myapp.appspot.com" instead of "https://1.myapp.appspot.com." If you continue to use "https://1.myapp.appspot.com" the certificate will not match, which will result in an error for any User-Agent that expects the URL and certificate to match exactly.

Dispatch file

You can create a dispatch file to override the default routing for URLs that do not specify a version (described above). This lets you route incoming requests to a specific module based on the path or hostname in the URL. For example, say that you want to route mobile requests like http://simple-sample.appspot.com/mobile/ to a mobile frontend, route worker requests like http://simple-sample.appspot.com/work/ to a static backend, and serve all static content from the default module.

To do this you can create a custom routing with a dispatch.xml file. The file should be placed in the
WEB-INF directory of the default module.

The dispatch file can contain up to 10 routing rules. When specifying the url string, neither the hostname nor the path can be longer than 100 characters.

As you can see, dispatch.xml includes support for glob characters. Glob characters can be used only before the hostname and at the end of the path. If you prefer general routing rules that match many possible requests, you could specify the following:

<!-- Send any path that begins with “simple-sample.appspot.com/mobile” to the mobile-frontend module. -->
<url>simple-sample.appspot.com/mobile*</url>
<module>mobile-frontend</module>
<!-- Send any domain/sub-domain with a path that starts with “work” to the static backend module. -->
<url>*/work*</url>
<module>static-backend</module>

The dispatch file can be uploaded together with your module files using a single
appcfg update
command. The names of all the modules used in the dispatch file must
appear before the dispatch file itself. You can also upload the dispatch file
separately, using the appcfg update_dispatch
command. Be sure that all the modules mentioned in the file
have already been uploaded before using this command.

Routing in the development server

Addressing instances

The development server creates all instances at startup. Note that at this
time basic scaling instances are not supported on the 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 modules. It looks
like this in the server log:

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

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

Module

Instance

Development Server Address

App Engine Address

module2-auto

(not used)

http://localhost:37251/

http://v1.module2-auto.appid.appspot.com/

manualmodule

0

http://localhost:43190/

http://0.v1.manualmodule.appid.appspot.com/

manualmodule

1

http://localhost:52642/

http://1.v1.manualmodule.appid.appspot.com/

manualmodule

(not used)

http://localhost:12361/

http://v1.manualmodule.appid.appspot.com/

Dispatch files

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

Dispatch files and cron files

A routing conflict can occur if your app has a dispatch file and a
cron.xml file, and the same URL path appears in both files. The cron file
may specify a target module that is not the same as the module associated with
the URL in the dispatch file. When the cron job runs, the URL is routed via the
dispatch file, and the module specified there overrides the
target in the cron file.